ts-data-forge 1.0.0

package/src/globals.d.mts

@@ -0,0 +1,38 @@
+/// <reference types="ts-type-forge" />
+
+type SmallUint = SmallInt<'>=0'>;
+type PositiveSmallInt = SmallInt<'>0'>;
+
+/**
+ * Represents the type of keys that can be used in a standard JavaScript Map.
+ */
+type MapSetKeyType = Primitive;
+
+// https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/length
+// https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/String/length
+// Max array length : 2^32 - 1
+// Max string length : 2^53 - 1
+
+declare namespace SizeType {
+  type Arr = Uint32;
+  type TypedArray = SafeUint;
+  type Str = SafeUint;
+
+  type ArrSearchResult = Arr | -1;
+  type TypedArraySearchResult = TypedArray | -1;
+  type StrSearchResult = Str | -1;
+
+  type ArgArr = WithSmallInt<NormalizeBrandUnion<NegativeInt32 | Arr>>;
+  type ArgTypedArray = WithSmallInt<SafeInt>;
+  type ArgStr = WithSmallInt<SafeInt>;
+
+  type ArgArrPositive = WithSmallInt<IntersectBrand<PositiveNumber, Arr>>;
+  type ArgTypedArrayPositive = WithSmallInt<
+    IntersectBrand<PositiveNumber, TypedArray>
+  >;
+  type ArgStrPositive = WithSmallInt<IntersectBrand<PositiveNumber, Str>>;
+
+  type ArgArrNonNegative = WithSmallInt<Arr>;
+  type ArgTypedArrayNonNegative = WithSmallInt<TypedArray>;
+  type ArgStrNonNegative = WithSmallInt<Str>;
+}

package/src/guard/has-key.mts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ *
+ * **Type Narrowing Behavior:**
+ * - 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();
+ *
+ * if (hasKey(dynamicObj, userInput)) {
+ *   // Safe to access the dynamic key
+ *   const value = dynamicObj[userInput]; // Type: unknown
+ *   console.log(`Value for ${userInput}:`, value);
+ * } 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
+ * Combining with other type guards 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);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link keyIsIn} - Similar function that narrows the key type instead of the object type
+ */
+export const hasKey = <
+  const R extends UnknownRecord,
+  const K extends PropertyKey,
+>(
+  obj: R,
+  key: K,
+): obj is HasKeyReturnType<R, K> => Object.hasOwn(obj, key);
+
+/**
+ * @internal
+ * When R is a union type (including the case with only one element), if any element in the union
+ * contains K as a key, returns a type that narrows the union to only those elements that contain K as a key.
+ * If none of the elements in the union contain K as a key, returns `ReadonlyRecord<K, unknown>`.
+ * The result is made readonly.
+ */
+export type HasKeyReturnType<
+  R extends UnknownRecord,
+  K extends PropertyKey,
+> = R extends R // union distribution
+  ? K extends keyof R
+    ? string extends keyof R
+      ? ReadonlyRecord<K, R[keyof R]> & R
+      : number extends keyof R
+        ? ReadonlyRecord<K, R[keyof R]> & R
+        : symbol extends keyof R
+          ? ReadonlyRecord<K, R[keyof R]> & R
+          : R
+    : never // omit union member that does not have key K
+  : never; // dummy case for union distribution

package/src/guard/has-key.test.mts

@@ -0,0 +1,219 @@
+import { expectType } from '../expect-type.mjs';
+import { hasKey, type HasKeyReturnType } from './has-key.mjs';
+
+{
+  expectType<
+    HasKeyReturnType<Readonly<{ a: 0 }> | Readonly<{ b: 1 }>, 'a'>,
+    Readonly<{ a: 0 }>
+  >('=');
+
+  expectType<
+    HasKeyReturnType<Readonly<{ a: 0 }> | Readonly<{ b: 1 }>, 'b'>,
+    Readonly<{ b: 1 }>
+  >('=');
+
+  expectType<
+    HasKeyReturnType<Readonly<{ a: 0 }> | Readonly<{ b: 1 }>, 'd'>,
+    never
+  >('=');
+
+  expectType<
+    HasKeyReturnType<
+      | Readonly<{ a: 0 }>
+      | Readonly<{ a: 1; b: 1 }>
+      | Readonly<{ b: 2 }>
+      | Readonly<{ c: 3 }>,
+      'a'
+    >,
+    Readonly<{ a: 0 }> | Readonly<{ a: 1; b: 1 }>
+  >('=');
+
+  expectType<
+    HasKeyReturnType<
+      | Readonly<{ a: 0 }>
+      | Readonly<{ a: 1; b: 1 }>
+      | Readonly<{ b: 2 }>
+      | Readonly<{ c: 3 }>,
+      'b'
+    >,
+    Readonly<{ a: 1; b: 1 }> | Readonly<{ b: 2 }>
+  >('=');
+
+  expectType<
+    HasKeyReturnType<
+      | ReadonlyRecord<string, number>
+      | Readonly<{ a: 0 }>
+      | Readonly<{ a: 1; b: 1 }>
+      | Readonly<{ b: 2 }>,
+      'a'
+    >,
+    | Readonly<{ a: 0 }>
+    | Readonly<{ a: 1; b: 1 }>
+    | (ReadonlyRecord<'a', number> & ReadonlyRecord<string, number>)
+  >('=');
+
+  expectType<
+    HasKeyReturnType<ReadonlyRecord<string, unknown>, 'a'>,
+    ReadonlyRecord<'a', unknown> & ReadonlyRecord<string, unknown>
+  >('=');
+}
+
+{
+  type R = Readonly<{ a: 0 }> | Readonly<{ b: 1 }>;
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const obj: R = { a: 0 } as R;
+
+  if (hasKey(obj, 'a')) {
+    expectType<typeof obj.a, 0>('=');
+    expectType<typeof obj, Readonly<{ a: 0 }>>('=');
+  }
+
+  if (hasKey(obj, 'c')) {
+    expectType<typeof obj, never>('=');
+  }
+}
+
+{
+  type R =
+    | Readonly<{ a: 0 }>
+    | Readonly<{ a: 1; b: 1 }>
+    | Readonly<{ b: 2 }>
+    | Readonly<{ c: 3 }>;
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const obj: R = { a: 0 } as R;
+
+  if (hasKey(obj, 'a') && hasKey(obj, 'b')) {
+    expectType<typeof obj.a, 1>('=');
+    expectType<typeof obj.b, 1>('=');
+    expectType<typeof obj, Readonly<{ a: 1; b: 1 }>>('=');
+  }
+}
+
+{
+  type R =
+    | ReadonlyRecord<string, number>
+    | Readonly<{ a: 0 }>
+    | Readonly<{ a: 1; b: 1 }>
+    | Readonly<{ b: 2 }>;
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const obj: R = { a: 0 } as R;
+
+  expectType<
+    R,
+    | ReadonlyRecord<string, number>
+    | Readonly<{ a: 0 }>
+    | Readonly<{ a: 1; b: 1 }>
+    | Readonly<{ b: 2 }>
+  >('=');
+
+  if (hasKey(obj, 'a')) {
+    expectType<typeof obj.a, number>('=');
+
+    expectType<
+      typeof obj,
+      | Readonly<{ a: 0 }>
+      | Readonly<{ a: 1; b: 1 }>
+      | (ReadonlyRecord<'a', number> & ReadonlyRecord<string, number>)
+    >('=');
+  }
+
+  if (hasKey(obj, 'a') && hasKey(obj, 'b')) {
+    expectType<typeof obj.a, number>('=');
+    expectType<typeof obj.b, number>('=');
+    expectType<
+      typeof obj,
+      | Readonly<{ a: 1; b: 1 }>
+      | (ReadonlyRecord<'a', number> &
+          ReadonlyRecord<'b', number> &
+          ReadonlyRecord<string, number>)
+    >('=');
+  }
+}
+
+{
+  const o: ReadonlyRecord<string, unknown> = { a: 0, b: 1 };
+
+  if (hasKey(o, 'a')) {
+    expectType<typeof o.a, unknown>('=');
+    expectType<
+      typeof o,
+      ReadonlyRecord<'a', unknown> & ReadonlyRecord<string, unknown>
+    >('=');
+  }
+
+  if (hasKey(o, 'c')) {
+    expectType<typeof o.c, unknown>('=');
+    expectType<
+      typeof o,
+      ReadonlyRecord<'c', unknown> & ReadonlyRecord<string, unknown>
+    >('=');
+  }
+
+  if (hasKey(o, 'a') && hasKey(o, 'b')) {
+    expectType<typeof o.a, unknown>('=');
+    expectType<typeof o.b, unknown>('=');
+    expectType<
+      typeof o,
+      ReadonlyRecord<'a', unknown> &
+        ReadonlyRecord<'b', unknown> &
+        ReadonlyRecord<string, unknown>
+    >('=');
+  }
+
+  {
+    /**
+     * @note Simply using `R & Record<K, R[K]>` as the return type of hasKey may seem good enough
+     * since it works as intended for cases like `obj: Record<string, unknown>`.
+     * However, for finite-sized types like `obj: { a: 0 } | { b: 1 }`,
+     * filtering with `hasKey(obj, 'a')` causes `obj.a` to widen to `unknown` instead of `0`,
+     * which doesn't work well.
+     */
+
+    const hasOwnNaive = <R extends UnknownRecord, K extends string>(
+      obj: R,
+      key: K,
+    ): obj is R & Record<K, R[K]> => hasKey(obj, key);
+
+    {
+      type O =
+        | Readonly<{ a: 0 }>
+        | Readonly<{ a: 1; b: 1 }>
+        | Readonly<{ b: 2 }>
+        | Record<string, number>;
+
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const o2 = { b: 2 } as O;
+
+      if (hasOwnNaive(o2, 'a')) {
+        expectType<typeof o2.a, unknown>('=');
+      }
+
+      // eslint-disable-next-line no-restricted-syntax
+      if ('a' in o2) {
+        expectType<typeof o2.a, number>('=');
+      }
+    }
+
+    {
+      type O =
+        | Readonly<{ a: 0 }>
+        | Readonly<{ a: 1; b: 1 }>
+        | Readonly<{ b: 2 }>;
+
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const o2 = { b: 2 } as O;
+
+      if (hasOwnNaive(o2, 'a')) {
+        expectType<typeof o2.a, unknown>('=');
+      }
+
+      // eslint-disable-next-line no-restricted-syntax
+      if ('a' in o2) {
+        expectType<typeof o2.a, 0 | 1>('=');
+      }
+    }
+  }
+}

package/src/guard/index.mts

@@ -0,0 +1,7 @@
+export * from './has-key.mjs';
+export * from './is-non-empty-string.mjs';
+export * from './is-non-null-object.mjs';
+export * from './is-primitive.mjs';
+export * from './is-record.mjs';
+export * from './is-type.mjs';
+export * from './key-is-in.mjs';

package/src/guard/is-non-empty-string.mts

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ *
+ * **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,
+ *   undefined,
+ *   " "
+ * ];
+ *
+ * const validResponses = responses.filter(isNonEmptyString);
+ * // validResponses is now string[] containing ["hello", "world", " "]
+ *
+ * validResponses.forEach(response => {
+ *   // Each response is guaranteed to be a non-empty string
+ *   console.log(response.trim().toUpperCase());
+ * });
+ * ```
+ */
+export const isNonEmptyString = <S extends string | null | undefined>(
+  s: S,
+): s is RelaxedExclude<NonNullable<S>, ''> =>
+  typeof s === 'string' && s.length > 0;

package/src/guard/is-non-empty-string.test.mts

@@ -0,0 +1,91 @@
+import { expectType } from '../expect-type.mjs';
+import { isNonEmptyString } from './is-non-empty-string.mjs';
+
+describe('isNonEmptyString', () => {
+  test('should return true for non-empty strings', () => {
+    expect(isNonEmptyString('hello')).toBe(true);
+    expect(isNonEmptyString('a')).toBe(true);
+    expect(isNonEmptyString(' ')).toBe(true); // Space is not empty
+    expect(isNonEmptyString('  multiple spaces  ')).toBe(true);
+    expect(isNonEmptyString('123')).toBe(true);
+    expect(isNonEmptyString('special!@#$%')).toBe(true);
+  });
+
+  test('should return false for empty string', () => {
+    expect(isNonEmptyString('')).toBe(false);
+  });
+
+  test('should return false for non-string values', () => {
+    expect(isNonEmptyString(null)).toBe(false);
+    expect(isNonEmptyString(undefined)).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString(42)).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString(0)).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString(true)).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString(false)).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString({})).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString([])).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString(['string'])).toBe(false);
+    // @ts-expect-error Testing non-string types
+    expect(isNonEmptyString(() => 'string')).toBe(false);
+  });
+
+  test('should act as a type guard', () => {
+    const value: unknown = 'test';
+
+    // @ts-expect-error Testing non-string types
+    if (isNonEmptyString(value)) {
+      expectType<typeof value, string>('=');
+      // TypeScript knows it's a string
+      expect(value.length).toBeGreaterThan(0);
+      expect(value.charAt(0)).toBe('t');
+    }
+  });
+
+  test('should narrow string | undefined | null types', () => {
+    const maybeString: string | undefined | null = 'hello';
+
+    if (isNonEmptyString(maybeString)) {
+      expectType<typeof maybeString, string>('=');
+      expect(maybeString.toUpperCase()).toBe('HELLO');
+    }
+  });
+
+  test('should work in filter operations', () => {
+    const mixed: unknown[] = [
+      'valid',
+      '',
+      null,
+      'another',
+      42,
+      undefined,
+      'third',
+      false,
+    ];
+
+    // @ts-expect-error Testing non-string types
+    const nonEmptyStrings = mixed.filter(isNonEmptyString);
+    expect(nonEmptyStrings).toStrictEqual(['valid', 'another', 'third']);
+  });
+
+  test('should handle string edge cases', () => {
+    expect(isNonEmptyString('\n')).toBe(true); // Newline
+    expect(isNonEmptyString('\t')).toBe(true); // Tab
+    expect(isNonEmptyString('\r')).toBe(true); // Carriage return
+    expect(isNonEmptyString('\0')).toBe(true); // Null character
+    expect(isNonEmptyString('🎉')).toBe(true); // Emoji
+    expect(isNonEmptyString('你好')).toBe(true); // Unicode characters
+  });
+
+  test('should not accept String objects', () => {
+    // @ts-expect-error Testing non-string types
+    // eslint-disable-next-line no-new-wrappers
+    expect(isNonEmptyString(new String('hello') as unknown)).toBe(false);
+  });
+});

package/src/guard/is-non-null-object.mts

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ *
+ * **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');
+ * }
+ * ```
+ *
+ * @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
+ *
+ * objects.forEach(obj => {
+ *   // Each obj is guaranteed to be an object
+ *   console.log('Object type:', obj.constructor.name);
+ * });
+ * ```
+ *
+ * @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);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
+ */
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
+export const isNonNullObject = (u: unknown): u is object =>
+  typeof u === 'object' && u !== null;