ts-data-forge 3.3.0 → 4.0.0

package/dist/guard/has-key.mjs

@@ -1,91 +1,40 @@
 /**
- * Type guard function that checks if an object has a specific key as its own property.
+ * Type guard function that checks if an object has a specific key as its own
+ * property.
  *
- * This function uses `Object.hasOwn()` to check if the given object has the specified key
- * as its own property (not inherited). It acts as a type guard that narrows the type of the
- * object to guarantee the key exists, enabling type-safe property access.
+ * This function uses `Object.hasOwn()` to check if the given object has the
+ * specified key as its own property (not inherited). It acts as a type guard
+ * that narrows the type of the object to guarantee the key exists, enabling
+ * type-safe property access.
  *
  * **Type Narrowing Behavior:**
- * - When the guard returns `true`, TypeScript narrows the object type to include the checked key
+ *
+ * - When the guard returns `true`, TypeScript narrows the object type to include
+ *   the checked key
  * - For union types, only union members that contain the key are preserved
  * - The key's value type is preserved from the original object type when possible
  *
- * @template R - The type of the input object, must extend UnknownRecord
- * @template K - The type of the key to check for, must extend PropertyKey (string | number | symbol)
- * @param obj - The object to check for the presence of the key
- * @param key - The key to check for in the object
- * @returns `true` if the object has the specified key as its own property, `false` otherwise.
- *          When `true`, TypeScript narrows the object type to guarantee the key exists.
- *
  * @example
- * Basic usage with known object structure:
- * ```typescript
- * const obj = { a: 1, b: 'hello' };
- *
- * if (hasKey(obj, 'a')) {
- *   // obj is narrowed to guarantee 'a' exists
- *   console.log(obj.a); // TypeScript knows 'a' exists and is type number
- *   // No need for optional chaining or undefined checks
- * }
  *
- * if (hasKey(obj, 'c')) {
- *   // This block won't execute at runtime
- *   console.log(obj.c); // But TypeScript would know 'c' exists if it did
- * }
- * ```
- *
- * @example
- * Working with dynamic objects and unknown keys:
- * ```typescript
- * const dynamicObj: Record<string, unknown> = { x: 10, y: 20 };
- * const userInput: string = getUserInput();
+ * ```ts
+ * const maybeUser: { id?: number; name?: string } = { id: 42 };
  *
- * if (hasKey(dynamicObj, userInput)) {
- *   // Safe to access the dynamic key
- *   const value = dynamicObj[userInput]; // Type: unknown
- *   console.log(`Value for ${userInput}:`, value);
+ * if (hasKey(maybeUser, 'id')) {
+ *   // `maybeUser` is now known to have an `id` property.
+ *   assert(maybeUser.id === 42);
  * } else {
- *   console.log(`Key '${userInput}' not found`);
- * }
- * ```
- *
- * @example
- * Type narrowing with union types:
- * ```typescript
- * type UserPreferences =
- *   | { theme: 'dark'; notifications: boolean }
- *   | { theme: 'light' }
- *   | { autoSave: true; interval: number };
- *
- * const preferences: UserPreferences = getPreferences();
- *
- * if (hasKey(preferences, 'theme')) {
- *   // preferences is narrowed to the first two union members
- *   console.log(preferences.theme); // 'dark' | 'light'
- * }
- *
- * if (hasKey(preferences, 'autoSave')) {
- *   // preferences is narrowed to the third union member
- *   console.log(preferences.interval); // number (we know this exists)
- * }
- * ```
- *
- * @example
- * Basic usage with isRecord for progressive narrowing:
- * ```typescript
- * const data: unknown = parseApiResponse();
- *
- * if (isRecord(data) && hasKey(data, 'user')) {
- *   // data is now Record<string, unknown> with guaranteed 'user' key
- *   const user = data.user;
- *
- *   if (isRecord(user) && hasKey(user, 'name')) {
- *     // Safely access nested properties
- *     console.log('User name:', user.name);
- *   }
+ *   assert.fail('Expected the object to contain the id key.');
  * }
  * ```
  *
+ * @template R - The type of the input object, must extend UnknownRecord
+ * @template K - The type of the key to check for, must extend PropertyKey
+ *   (string | number | symbol)
+ * @param obj - The object to check for the presence of the key
+ * @param key - The key to check for in the object
+ * @returns `true` if the object has the specified key as its own property,
+ *   `false` otherwise. When `true`, TypeScript narrows the object type to
+ *   guarantee the key exists.
  * @see {@link keyIsIn} - Similar function that narrows the key type instead of the object type
  */
 const hasKey = (obj, key) => Object.hasOwn(obj, key);

package/dist/guard/has-key.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"has-key.mjs","sources":["../../src/guard/has-key.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyFG;AACI,MAAM,MAAM,GAAG,CAIpB,GAAM,EACN,GAAM,KAC4B,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG;;;;"}
+{"version":3,"file":"has-key.mjs","sources":["../../src/guard/has-key.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCG;AACI,MAAM,MAAM,GAAG,CAIpB,GAAM,EACN,GAAM,KAC4B,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG;;;;"}

package/dist/guard/is-non-empty-string.d.mts

@@ -1,106 +1,39 @@
 /**
  * Type guard that checks if a value is a non-empty string.
  *
- * This function performs both a type check (ensuring the value is a string) and a length check
- * (ensuring the string is not empty). It acts as a type guard that narrows the input type to
- * exclude `null`, `undefined`, and empty strings.
+ * This function performs both a type check (ensuring the value is a string) and
+ * a length check (ensuring the string is not empty). It acts as a type guard
+ * that narrows the input type to exclude `null`, `undefined`, and empty
+ * strings.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Eliminates `null` and `undefined` from the type
  * - Excludes empty string (`""`) from the type
  * - Preserves literal string types when possible
  * - Whitespace-only strings are considered non-empty
  *
- * @template S - The input type, which can include `string`, `null`, or `undefined`
- * @param s - The value to check
- * @returns `true` if `s` is a string with length > 0, `false` otherwise.
- *          When `true`, TypeScript narrows the type to exclude empty strings and nullish values.
- *
- * @example
- * Basic usage with different string types:
- * ```typescript
- * isNonEmptyString("hello");    // true
- * isNonEmptyString(" ");        // true (whitespace is considered non-empty)
- * isNonEmptyString("\t\n");     // true (whitespace characters are non-empty)
- * isNonEmptyString("");         // false
- * isNonEmptyString(null);       // false
- * isNonEmptyString(undefined);  // false
- * ```
- *
- * @example
- * Type guard usage with nullable strings:
- * ```typescript
- * const userInput: string | null | undefined = getUserInput();
- *
- * if (isNonEmptyString(userInput)) {
- *   // userInput is now typed as non-empty string
- *   console.log(userInput.charAt(0));     // Safe to access string methods
- *   console.log(userInput.toUpperCase()); // No need for null checks
- *   const length = userInput.length;      // Guaranteed to be > 0
- * } else {
- *   console.log('No valid input provided');
- * }
- * ```
- *
- * @example
- * Working with literal string types:
- * ```typescript
- * type Status = "active" | "inactive" | "" | null;
- * const status: Status = getStatus();
- *
- * if (isNonEmptyString(status)) {
- *   // status is now typed as "active" | "inactive"
- *   console.log(`Status is: ${status}`);
- * }
- * ```
- *
  * @example
- * Form validation patterns:
- * ```typescript
- * interface FormData {
- *   name?: string;
- *   email?: string;
- *   phone?: string;
- * }
- *
- * function validateForm(data: FormData): string[] {
- *   const errors: string[] = [];
- *
- *   if (!isNonEmptyString(data.name)) {
- *     errors.push('Name is required');
- *   }
- *
- *   if (!isNonEmptyString(data.email)) {
- *     errors.push('Email is required');
- *   } else if (!data.email.includes('@')) {
- *     // Safe to access string methods after guard
- *     errors.push('Invalid email format');
- *   }
  *
- *   return errors;
- * }
- * ```
- *
- * @example
- * Filtering arrays of potentially empty strings:
- * ```typescript
- * const responses: (string | null | undefined)[] = [
- *   "hello",
- *   "",
- *   "world",
- *   null,
+ * ```ts
+ * const words: readonly (string | undefined)[] = [
+ *   'Ada',
  *   undefined,
- *   " "
- * ];
+ *   '',
+ *   'Lovelace',
+ * ] as const;
  *
- * const validResponses = responses.filter(isNonEmptyString);
- * // validResponses is now string[] containing ["hello", "world", " "]
+ * const nonEmpty = words.filter(isNonEmptyString);
  *
- * validResponses.forEach(response => {
- *   // Each response is guaranteed to be a non-empty string
- *   console.log(response.trim().toUpperCase());
- * });
+ * assert.deepStrictEqual(nonEmpty, ['Ada', 'Lovelace']);
  * ```
+ *
+ * @template S - The input type, which can include `string`, `null`, or
+ *   `undefined`
+ * @param s - The value to check
+ * @returns `true` if `s` is a string with length > 0, `false` otherwise. When
+ *   `true`, TypeScript narrows the type to exclude empty strings and nullish
+ *   values.
  */
 export declare const isNonEmptyString: <S extends string | null | undefined>(s: S) => s is RelaxedExclude<NonNullable<S>, "">;
 //# sourceMappingURL=is-non-empty-string.d.mts.map

package/dist/guard/is-non-empty-string.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"is-non-empty-string.d.mts","sourceRoot":"","sources":["../../src/guard/is-non-empty-string.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,EAClE,GAAG,CAAC,KACH,CAAC,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CACF,CAAC"}
+{"version":3,"file":"is-non-empty-string.d.mts","sourceRoot":"","sources":["../../src/guard/is-non-empty-string.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,EAClE,GAAG,CAAC,KACH,CAAC,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CACF,CAAC"}

package/dist/guard/is-non-empty-string.mjs

@@ -1,106 +1,39 @@
 /**
  * Type guard that checks if a value is a non-empty string.
  *
- * This function performs both a type check (ensuring the value is a string) and a length check
- * (ensuring the string is not empty). It acts as a type guard that narrows the input type to
- * exclude `null`, `undefined`, and empty strings.
+ * This function performs both a type check (ensuring the value is a string) and
+ * a length check (ensuring the string is not empty). It acts as a type guard
+ * that narrows the input type to exclude `null`, `undefined`, and empty
+ * strings.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Eliminates `null` and `undefined` from the type
  * - Excludes empty string (`""`) from the type
  * - Preserves literal string types when possible
  * - Whitespace-only strings are considered non-empty
  *
- * @template S - The input type, which can include `string`, `null`, or `undefined`
- * @param s - The value to check
- * @returns `true` if `s` is a string with length > 0, `false` otherwise.
- *          When `true`, TypeScript narrows the type to exclude empty strings and nullish values.
- *
- * @example
- * Basic usage with different string types:
- * ```typescript
- * isNonEmptyString("hello");    // true
- * isNonEmptyString(" ");        // true (whitespace is considered non-empty)
- * isNonEmptyString("\t\n");     // true (whitespace characters are non-empty)
- * isNonEmptyString("");         // false
- * isNonEmptyString(null);       // false
- * isNonEmptyString(undefined);  // false
- * ```
- *
- * @example
- * Type guard usage with nullable strings:
- * ```typescript
- * const userInput: string | null | undefined = getUserInput();
- *
- * if (isNonEmptyString(userInput)) {
- *   // userInput is now typed as non-empty string
- *   console.log(userInput.charAt(0));     // Safe to access string methods
- *   console.log(userInput.toUpperCase()); // No need for null checks
- *   const length = userInput.length;      // Guaranteed to be > 0
- * } else {
- *   console.log('No valid input provided');
- * }
- * ```
- *
- * @example
- * Working with literal string types:
- * ```typescript
- * type Status = "active" | "inactive" | "" | null;
- * const status: Status = getStatus();
- *
- * if (isNonEmptyString(status)) {
- *   // status is now typed as "active" | "inactive"
- *   console.log(`Status is: ${status}`);
- * }
- * ```
- *
  * @example
- * Form validation patterns:
- * ```typescript
- * interface FormData {
- *   name?: string;
- *   email?: string;
- *   phone?: string;
- * }
- *
- * function validateForm(data: FormData): string[] {
- *   const errors: string[] = [];
- *
- *   if (!isNonEmptyString(data.name)) {
- *     errors.push('Name is required');
- *   }
- *
- *   if (!isNonEmptyString(data.email)) {
- *     errors.push('Email is required');
- *   } else if (!data.email.includes('@')) {
- *     // Safe to access string methods after guard
- *     errors.push('Invalid email format');
- *   }
  *
- *   return errors;
- * }
- * ```
- *
- * @example
- * Filtering arrays of potentially empty strings:
- * ```typescript
- * const responses: (string | null | undefined)[] = [
- *   "hello",
- *   "",
- *   "world",
- *   null,
+ * ```ts
+ * const words: readonly (string | undefined)[] = [
+ *   'Ada',
  *   undefined,
- *   " "
- * ];
+ *   '',
+ *   'Lovelace',
+ * ] as const;
  *
- * const validResponses = responses.filter(isNonEmptyString);
- * // validResponses is now string[] containing ["hello", "world", " "]
+ * const nonEmpty = words.filter(isNonEmptyString);
  *
- * validResponses.forEach(response => {
- *   // Each response is guaranteed to be a non-empty string
- *   console.log(response.trim().toUpperCase());
- * });
+ * assert.deepStrictEqual(nonEmpty, ['Ada', 'Lovelace']);
  * ```
+ *
+ * @template S - The input type, which can include `string`, `null`, or
+ *   `undefined`
+ * @param s - The value to check
+ * @returns `true` if `s` is a string with length > 0, `false` otherwise. When
+ *   `true`, TypeScript narrows the type to exclude empty strings and nullish
+ *   values.
  */
 const isNonEmptyString = (s) => typeof s === 'string' && s.length > 0;
 

package/dist/guard/is-non-empty-string.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"is-non-empty-string.mjs","sources":["../../src/guard/is-non-empty-string.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGG;AACI,MAAM,gBAAgB,GAAG,CAC9B,CAAI,KAEJ,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG;;;;"}
+{"version":3,"file":"is-non-empty-string.mjs","sources":["../../src/guard/is-non-empty-string.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCG;AACI,MAAM,gBAAgB,GAAG,CAC9B,CAAI,KAEJ,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG;;;;"}

package/dist/guard/is-non-null-object.d.mts

@@ -1,104 +1,34 @@
 /**
  * Type guard that checks if a value is a non-null object.
  *
- * This function checks if a value has type `"object"` according to the `typeof` operator
- * and is not `null`. This includes all object types such as plain objects, arrays, dates,
- * regular expressions, and other object instances, but excludes functions.
+ * This function checks if a value has type `"object"` according to the `typeof`
+ * operator and is not `null`. This includes all object types such as plain
+ * objects, arrays, dates, regular expressions, and other object instances, but
+ * excludes functions.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Narrows `unknown` to `object`
  * - Excludes `null`, `undefined`, and all primitive types
  * - Excludes functions (they have `typeof` === `"function"`, not `"object"`)
  * - Includes arrays, dates, regex, and other object instances
  *
- * **Note:** This function returns `true` for arrays. If you need to check for plain objects
- * specifically (excluding arrays), use `isRecord()` instead.
- *
- * @param u - The value to check
- * @returns `true` if `u` is an object and not `null`, `false` otherwise.
- *          When `true`, TypeScript narrows the type to `object`.
- *
- * @example
- * Basic usage with different value types:
- * ```typescript
- * isNonNullObject({});           // true (plain object)
- * isNonNullObject([]);           // true (arrays are objects)
- * isNonNullObject(new Date());   // true (Date instance)
- * isNonNullObject(/regex/);      // true (RegExp instance)
- * isNonNullObject(new Map());    // true (Map instance)
- * isNonNullObject(null);         // false (null is not considered object here)
- * isNonNullObject(undefined);    // false (primitive)
- * isNonNullObject("string");     // false (primitive)
- * isNonNullObject(42);           // false (primitive)
- * isNonNullObject(true);         // false (primitive)
- * isNonNullObject(() => {});     // false (functions are not objects in this context)
- * ```
- *
- * @example
- * Type guard usage with unknown values:
- * ```typescript
- * const value: unknown = parseJsonData();
- *
- * if (isNonNullObject(value)) {
- *   // value is now typed as object
- *   console.log('Value is an object');
- *
- *   // You can now safely use object-specific operations
- *   console.log(Object.keys(value));      // Safe to call Object.keys
- *   console.log(value.toString());        // Safe to call methods
- *
- *   // But you may need additional checks for specific object types
- *   if (Array.isArray(value)) {
- *     console.log('It\'s an array with length:', value.length);
- *   }
- * } else {
- *   console.log('Value is not an object');
- * }
- * ```
+ * **Note:** This function returns `true` for arrays. If you need to check for
+ * plain objects specifically (excluding arrays), use `isRecord()` instead.
  *
  * @example
- * Filtering arrays to find objects:
- * ```typescript
- * const mixedArray: unknown[] = [
- *   { name: 'John' },
- *   'string',
- *   [1, 2, 3],
- *   42,
- *   null,
- *   new Date(),
- *   () => 'function'
- * ];
  *
- * const objects = mixedArray.filter(isNonNullObject);
- * // objects contains: [{ name: 'John' }, [1, 2, 3], Date instance]
- * // Note: includes both plain objects and arrays
+ * ```ts
+ * const mixed: unknown[] = [{ id: 1 }, null, 'Ada'] as const;
  *
- * objects.forEach(obj => {
- *   // Each obj is guaranteed to be an object
- *   console.log('Object type:', obj.constructor.name);
- * });
- * ```
+ * const objects = mixed.filter(isNonNullObject);
  *
- * @example
- * Progressive type narrowing with other guards:
- * ```typescript
- * const apiResponse: unknown = await fetchData();
- *
- * if (isNonNullObject(apiResponse)) {
- *   // apiResponse is now object
- *
- *   if (isRecord(apiResponse)) {
- *     // Further narrowed to UnknownRecord (plain object, not array)
- *
- *     if (hasKey(apiResponse, 'status')) {
- *       console.log('API status:', apiResponse.status);
- *     }
- *   } else if (Array.isArray(apiResponse)) {
- *     console.log('Response is an array with length:', apiResponse.length);
- *   }
- * }
+ * assert.deepStrictEqual(objects, [{ id: 1 }]);
  * ```
  *
+ * @param u - The value to check
+ * @returns `true` if `u` is an object and not `null`, `false` otherwise. When
+ *   `true`, TypeScript narrows the type to `object`.
  * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
  */
 export declare const isNonNullObject: (u: unknown) => u is object;

package/dist/guard/is-non-null-object.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"is-non-null-object.d.mts","sourceRoot":"","sources":["../../src/guard/is-non-null-object.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,MACb,CAAC"}
+{"version":3,"file":"is-non-null-object.d.mts","sourceRoot":"","sources":["../../src/guard/is-non-null-object.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,MACb,CAAC"}

package/dist/guard/is-non-null-object.mjs

@@ -1,104 +1,34 @@
 /**
  * Type guard that checks if a value is a non-null object.
  *
- * This function checks if a value has type `"object"` according to the `typeof` operator
- * and is not `null`. This includes all object types such as plain objects, arrays, dates,
- * regular expressions, and other object instances, but excludes functions.
+ * This function checks if a value has type `"object"` according to the `typeof`
+ * operator and is not `null`. This includes all object types such as plain
+ * objects, arrays, dates, regular expressions, and other object instances, but
+ * excludes functions.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Narrows `unknown` to `object`
  * - Excludes `null`, `undefined`, and all primitive types
  * - Excludes functions (they have `typeof` === `"function"`, not `"object"`)
  * - Includes arrays, dates, regex, and other object instances
  *
- * **Note:** This function returns `true` for arrays. If you need to check for plain objects
- * specifically (excluding arrays), use `isRecord()` instead.
- *
- * @param u - The value to check
- * @returns `true` if `u` is an object and not `null`, `false` otherwise.
- *          When `true`, TypeScript narrows the type to `object`.
- *
- * @example
- * Basic usage with different value types:
- * ```typescript
- * isNonNullObject({});           // true (plain object)
- * isNonNullObject([]);           // true (arrays are objects)
- * isNonNullObject(new Date());   // true (Date instance)
- * isNonNullObject(/regex/);      // true (RegExp instance)
- * isNonNullObject(new Map());    // true (Map instance)
- * isNonNullObject(null);         // false (null is not considered object here)
- * isNonNullObject(undefined);    // false (primitive)
- * isNonNullObject("string");     // false (primitive)
- * isNonNullObject(42);           // false (primitive)
- * isNonNullObject(true);         // false (primitive)
- * isNonNullObject(() => {});     // false (functions are not objects in this context)
- * ```
- *
- * @example
- * Type guard usage with unknown values:
- * ```typescript
- * const value: unknown = parseJsonData();
- *
- * if (isNonNullObject(value)) {
- *   // value is now typed as object
- *   console.log('Value is an object');
- *
- *   // You can now safely use object-specific operations
- *   console.log(Object.keys(value));      // Safe to call Object.keys
- *   console.log(value.toString());        // Safe to call methods
- *
- *   // But you may need additional checks for specific object types
- *   if (Array.isArray(value)) {
- *     console.log('It\'s an array with length:', value.length);
- *   }
- * } else {
- *   console.log('Value is not an object');
- * }
- * ```
+ * **Note:** This function returns `true` for arrays. If you need to check for
+ * plain objects specifically (excluding arrays), use `isRecord()` instead.
  *
  * @example
- * Filtering arrays to find objects:
- * ```typescript
- * const mixedArray: unknown[] = [
- *   { name: 'John' },
- *   'string',
- *   [1, 2, 3],
- *   42,
- *   null,
- *   new Date(),
- *   () => 'function'
- * ];
  *
- * const objects = mixedArray.filter(isNonNullObject);
- * // objects contains: [{ name: 'John' }, [1, 2, 3], Date instance]
- * // Note: includes both plain objects and arrays
+ * ```ts
+ * const mixed: unknown[] = [{ id: 1 }, null, 'Ada'] as const;
  *
- * objects.forEach(obj => {
- *   // Each obj is guaranteed to be an object
- *   console.log('Object type:', obj.constructor.name);
- * });
- * ```
+ * const objects = mixed.filter(isNonNullObject);
  *
- * @example
- * Progressive type narrowing with other guards:
- * ```typescript
- * const apiResponse: unknown = await fetchData();
- *
- * if (isNonNullObject(apiResponse)) {
- *   // apiResponse is now object
- *
- *   if (isRecord(apiResponse)) {
- *     // Further narrowed to UnknownRecord (plain object, not array)
- *
- *     if (hasKey(apiResponse, 'status')) {
- *       console.log('API status:', apiResponse.status);
- *     }
- *   } else if (Array.isArray(apiResponse)) {
- *     console.log('Response is an array with length:', apiResponse.length);
- *   }
- * }
+ * assert.deepStrictEqual(objects, [{ id: 1 }]);
  * ```
  *
+ * @param u - The value to check
+ * @returns `true` if `u` is an object and not `null`, `false` otherwise. When
+ *   `true`, TypeScript narrows the type to `object`.
  * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
  */
 // eslint-disable-next-line @typescript-eslint/no-restricted-types

package/dist/guard/is-non-null-object.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"is-non-null-object.mjs","sources":["../../src/guard/is-non-null-object.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGG;AACH;AACO,MAAM,eAAe,GAAG,CAAC,CAAU,KACxC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK;;;;"}
+{"version":3,"file":"is-non-null-object.mjs","sources":["../../src/guard/is-non-null-object.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AACH;AACO,MAAM,eAAe,GAAG,CAAC,CAAU,KACxC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK;;;;"}