Added assertObject / isRecord.

Author: typhonrt

src/functions.ts

@@ -6,6 +6,38 @@
 
 export * from 'klona/full';
 
+/**
+ * Asserts that a value is an object, not null, and not an array.
+ *
+ * Unlike {@link isObject}, this function does **not** narrow the value to a generic indexable structure. Instead, it
+ * preserves the **existing** static type of the variable. This makes it ideal for validating option objects or
+ * interface-based inputs where all properties may be optional.
+ *
+ * Use this function when:
+ * ```
+ *   - You expect a value to be an object at runtime, **and**
+ *   - You want to keep its compile-time type intact after validation.
+ * ```
+ *
+ * @example
+ * interface Options { flag?: boolean; value?: number; }
+ *
+ * function run(opts: Options = {}) {
+ *   assertObject(opts, `'opts' is not an object.`);  // `opts` remains `Options`, not widened or reduced.
+ *   opts.value;                                      // Fully typed access remains available.
+ * }
+ *
+ * @throws {TypeError} if the value is null, non-object, or an array.
+ *
+ * @param value - The value to validate.
+ *
+ * @param errorMsg - Optional message used for the thrown TypeError.
+ */
+export function assertObject(value: unknown, errorMsg: string = 'Expected an object.'): asserts value is object
+{
+   if (value === null || typeof value !== 'object' || Array.isArray(value)) { throw new TypeError(errorMsg); }
+}
+
 /**
  * Freezes all entries traversed that are objects including entries in arrays.
  *
@@ -484,35 +516,121 @@ export function isIterable<T>(value: unknown): value is Iterable<T>
    return value !== null && typeof value === 'object' && typeof (value as any)[Symbol.iterator] === 'function';
 }
 
+export function isObject<T extends object>(value: T): value is T;
+
 /**
- * Tests for whether object is not null, typeof object, and not an array.
+ * Runtime check for whether a value is an object:
+ * ```
+ * - typeof === 'object'
+ * - not null
+ * - not an array
+ * ```
  *
- * @param value - Any value.
+ * This function performs **type narrowing**. If the check succeeds, TypeScript refines the type of `value` to `T`,
+ * allowing known object types (interfaces, classes, mapped structures) to retain their original shape.
+ *
+ * Type Behavior:
+ * - When called with a value that already has a specific object type (interface or shaped object), that type is
+ *   preserved after narrowing. Property access remains fully typed.
+ *
+ * - When called with `unknown`, `any`, or an untyped object literal, `T` becomes `object`, ensuring only that a
+ *   non-null object exists. No indexing or deep property inference is provided in this case.
+ *
+ * In other words:
+ * ```
+ * - Known object type   → remains that type (preferred behavior)
+ * - Unknown / untyped   → narrows only to `object`
+ * ```
  *
- * @returns Is it an object.
+ * Use this when you want runtime object validation **and** want to preserve typing when a value is already known to be
+ * a specific object type. If you instead need to **retain** the declared type regardless of narrowing, use
+ * {@link assertObject}. If you need indexable key / value access use a dedicated record check such as
+ * {@link isRecord} or {@link isPlainObject}.
+ *
+ * @param value - Any value to check.
+ *
+ * @returns True if the value is a non-null object and not an array.
  */
-export function isObject<T extends object>(value: T | unknown): value is T
+export function isObject(value: unknown): value is object;
+export function isObject(value: unknown): value is object
 {
    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+export function isPlainObject<T extends object>(value: T): value is T;
+
 /**
- * Tests for whether the given value is a plain object.
+ * Determines whether a value is a **plain** object.
+ *
+ * A plain object is one whose prototype is either:
+ *   - `Object.prototype` (created via `{}` or `new Object()`)
+ *   - `null` (created via `Object.create(null)`)
+ *
+ * This excludes arrays, functions, class instances, DOM objects, and any object with a custom prototype. In other
+ * words, this function detects JSON-like dictionary objects rather than structural or callable object types.
+ *
+ * Type Behavior:
+ * - If the input already has a known object type `T`, that type is preserved after narrowing.
+ * - If the input is `unknown` or untyped the result narrows to `Record<string, unknown>` allowing safe keyed access.
  *
- * An object is plain if it is created by either: `{}`, `new Object()` or `Object.create(null)`.
+ * Useful when validating configuration objects, cloning or merging data, performing deep equality, or working with
+ * structured JSON where non-plain / prototype values would be considered invalid.
  *
- * @param value - Any value
+ * @example
+ * const a = { x: 1 };
+ * isPlainObject(a);   // true
+ *
+ * class Foo {}
+ * isPlainObject(new Foo()); // false
+ *
+ * @example
+ * let data: unknown = getValue();
+ * if (isPlainObject(data)) {
+ *   data.foo;         // ok — key is `unknown`, but structure is guaranteed.
+ * }
+ *
+ * @param value - Any value to evaluate.
  *
- * @returns Is it a plain object.
+ * @returns True if the value is a plain object with no special prototype.
  */
-export function isPlainObject<T extends object>(value: unknown): value is T
+export function isPlainObject(value: unknown): value is Record<string, unknown>;
+export function isPlainObject(value: unknown): value is Record<string, unknown>
 {
    if (Object.prototype.toString.call(value) !== '[object Object]') { return false; }
 
    const prototype: any = Object.getPrototypeOf(value);
    return prototype === null || prototype === Object.prototype;
 }
 
+/**
+ * Checks whether a value is a generic key / value object / `Record<string, unknown>`.
+ *
+ * A record in this context means:
+ *   - `typeof value === 'object'`
+ *   - value is not `null`
+ *   - value is not an array
+ *
+ * Unlike {@link isObject}, this function does **not** attempt to preserve the original object type. All successful
+ * results narrow to `Record<string, unknown>` making the returned value safe for key-indexed access but without any
+ * knowledge of property names or expected value types.
+ *
+ * This is useful when processing untyped JSON-like data structures, dynamic configuration blocks, response bodies,
+ * or any case where a dictionary-style object is expected rather than a typed interface value.
+ *
+ * Contrast With:
+ * - {@link isObject} → preserves known object types where possible; use when typing should remain intact.
+ * - {@link isPlainObject} → narrows to plain JSON objects only (no prototypes, no class instances).
+ * - `isRecord()` → always narrows to a dictionary-style record for keyed lookup.
+ *
+ * @param value - Any value to test.
+ *
+ * @returns True if the value is an object that is neither null nor an array.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown>
+{
+   return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /**
  * Safely returns keys on an object or an empty array if not an object.
  *

src/plugin.ts

@@ -11,6 +11,7 @@ import * as OU from './functions.js';
  *
  * Wires up object util functions on the plugin eventbus. The following event bindings are available:
  * ```
+ * - `typhonjs:utils:object:assert`: Invokes `assertObject`.
  * - `typhonjs:utils:object:deep:freeze`: Invokes `deepFreeze`.
  * - `typhonjs:utils:object:deep:merge`: Invokes `deepMerge`.
  * - `typhonjs:utils:object:deep:seal`: Invokes `deepSeal`.
@@ -24,6 +25,7 @@ import * as OU from './functions.js';
  * - `typhonjs:utils:object:is:iterable`: Invokes `isIterable`.
  * - `typhonjs:utils:object:is:object`: Invokes `isObject`.
  * - `typhonjs:utils:object:is:object:plain`: Invokes `isPlainObject`.
+ * - `typhonjs:utils:object:is:record`: Invokes `isRecord`.
  * - `typhonjs:utils:object:keys`: Invokes `objectKeys`.
  * - `typhonjs:utils:object:klona`: Invokes `klona`.
  * - `typhonjs:utils:object:size`: Invokes `objectSize`.
@@ -49,6 +51,7 @@ export function onPluginLoad(ev)
       if (typeof options.guard === 'boolean') { guard = options.guard; }
    }
 
+   eventbus.on('typhonjs:utils:object:assert', OU.assertObject, void 0, { guard });
    eventbus.on('typhonjs:utils:object:deep:freeze', OU.deepFreeze, void 0, { guard });
    eventbus.on('typhonjs:utils:object:deep:merge', OU.deepMerge, void 0, { guard });
    eventbus.on('typhonjs:utils:object:deep:seal', OU.deepSeal, void 0, { guard });
@@ -64,6 +67,7 @@ export function onPluginLoad(ev)
    eventbus.on('typhonjs:utils:object:is:iterable', OU.isIterable, void 0, { guard });
    eventbus.on('typhonjs:utils:object:is:object', OU.isObject, void 0, { guard });
    eventbus.on('typhonjs:utils:object:is:object:plain', OU.isPlainObject, void 0, { guard });
+   eventbus.on('typhonjs:utils:object:is:record', OU.isRecord, void 0, { guard });
    eventbus.on('typhonjs:utils:object:keys', OU.objectKeys, void 0, { guard });
    eventbus.on('typhonjs:utils:object:klona', OU.klona, void 0, { guard });
    eventbus.on('typhonjs:utils:object:size', OU.objectSize, void 0, { guard });

test/src/functions.test.ts

@@ -94,6 +94,21 @@ const s_VERIFY_SAFESET_SUB = `{"a":0,"b":0,"c":0,"array":[0,0,0],"level1":{"d":0
 
 describe('ObjectUtil:', () =>
 {
+   it('assertObject', () =>
+   {
+      assert.throws(() => ObjectUtil.assertObject(false), 'Expected an object.');
+      assert.throws(() => ObjectUtil.assertObject(null), 'Expected an object.');
+      assert.throws(() => ObjectUtil.assertObject(void 0), 'Expected an object.');
+      assert.throws(() => ObjectUtil.assertObject([]), 'Expected an object.');
+
+      assert.throws(() => ObjectUtil.assertObject(void 0, 'Custom error message'), 'Custom error message');
+
+      // No-op visual type erasure check.
+      const val: NoOpObj = { a: 123 };
+      ObjectUtil.assertObject(val);
+      expectTypeOf(val).toEqualTypeOf<NoOpObj>();
+   });
+
    it('deepFreeze w/ skipKeys:', () =>
    {
       const testObj = ObjectUtil.klona(s_OBJECT_DEEP);
@@ -728,6 +743,25 @@ describe('ObjectUtil:', () =>
       if (ObjectUtil.isPlainObject(val)) { expectTypeOf(val).toEqualTypeOf<NoOpObj>(); }
    });
 
+   it('isRecord', () =>
+   {
+      class Test {}
+
+      assert.isFalse(ObjectUtil.isRecord(false));
+      assert.isFalse(ObjectUtil.isRecord(null));
+      assert.isFalse(ObjectUtil.isRecord(void 0));
+      assert.isFalse(ObjectUtil.isRecord('test'));
+
+      assert.isTrue(ObjectUtil.isRecord(new Test()));
+      assert.isTrue(ObjectUtil.isRecord({}));
+      assert.isTrue(ObjectUtil.isRecord(Object.create(null)));
+      assert.isTrue(ObjectUtil.isRecord(new Object())); // eslint-disable-line no-new-object
+
+      // No-op visual type check.
+      const val: NoOpObj = { a: 123 };
+      if (ObjectUtil.isRecord(val)) { expectTypeOf(val).toEqualTypeOf<Record<string, unknown>>(); }
+   });
+
    it('objectKeys', () =>
    {
       // @ts-expect-error