@cult-frog/primitives 0.1.0

package/dist/predicates/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/predicates/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAO9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAE1F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAC/C,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,CAAC,GACL,KAAK,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE7B"}

package/dist/predicates/record.js

@@ -0,0 +1,69 @@
+/**
+ * Checks if a value is a plain object, i.e. an object literal or an object created with
+ * `Object.create(null)`.
+ *
+ * Arrays, class instances and built-ins such as `Date`, `Map` and `RegExp` are rejected. This
+ * makes it suitable for validating parsed data such as JSON before reading its properties.
+ *
+ * Objects created in another realm (an iframe or a Node `vm` context) are also rejected, because
+ * their prototype is a different `Object.prototype`.
+ *
+ * @example
+ * ```ts
+ * isRecord({ id: 1 }); // true
+ * isRecord(Object.create(null)); // true
+ * isRecord([]); // false
+ * isRecord(new Date()); // false
+ * isRecord(null); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is a plain object, otherwise `false`.
+ */
+export function isRecord(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Checks if a value is not a plain object. This is the inverse of {@link isRecord}.
+ *
+ * @example
+ * ```ts
+ * isNotRecord(new Date()); // true
+ * isNotRecord([]); // true
+ * isNotRecord({ id: 1 }); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is not a plain object, otherwise `false`.
+ */
+export function isNotRecord(value) {
+    return !isRecord(value);
+}
+/**
+ * Checks if an object has the given key as its own property, narrowing the object so the
+ * property can be read.
+ *
+ * Inherited properties are not counted, so keys such as `toString` do not match. The property
+ * may still hold `undefined`.
+ *
+ * @example
+ * ```ts
+ * const data: unknown = JSON.parse(input);
+ *
+ * if (isRecord(data) && hasProperty(data, 'id') && isNumber(data.id)) {
+ *   data.id; // number
+ * }
+ * ```
+ *
+ * @param value - The object to check.
+ * @param key - The property key to look for.
+ * @returns `true` if `value` has `key` as an own property, otherwise `false`.
+ */
+export function hasProperty(value, key) {
+    return Object.hasOwn(value, key);
+}
+//# sourceMappingURL=record.js.map

package/dist/predicates/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/predicates/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAI,KAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,GAAM;IAEN,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC"}

package/dist/predicates/string.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Checks if a value is a string primitive. `String` wrapper objects are rejected.
+ *
+ * @example
+ * ```ts
+ * isString('hello'); // true
+ * isString(''); // true
+ * isString(42); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is a string, otherwise `false`.
+ */
+export declare function isString(value: unknown): value is string;
+//# sourceMappingURL=string.d.ts.map

package/dist/predicates/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/predicates/string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD"}

package/dist/predicates/string.js

@@ -0,0 +1,17 @@
+/**
+ * Checks if a value is a string primitive. `String` wrapper objects are rejected.
+ *
+ * @example
+ * ```ts
+ * isString('hello'); // true
+ * isString(''); // true
+ * isString(42); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is a string, otherwise `false`.
+ */
+export function isString(value) {
+    return typeof value === 'string';
+}
+//# sourceMappingURL=string.js.map

package/dist/predicates/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../../src/predicates/string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC"}

package/dist/predicates/undefined.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Checks if a value is `undefined`. `null` is not considered `undefined`; use {@link isNil} to
+ * check for both.
+ *
+ * @example
+ * ```ts
+ * isUndefined(undefined); // true
+ * isUndefined(null); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is `undefined`, otherwise `false`.
+ */
+export declare function isUndefined<T>(value: T | undefined): value is undefined;
+/**
+ * Checks if a value is not `undefined`, narrowing `undefined` out of its type. `null` passes
+ * this check; use {@link isNotNil} to exclude both.
+ *
+ * @example
+ * ```ts
+ * const lookups = ids.map((id) => cache.get(id)); // (User | undefined)[]
+ * const cached = lookups.filter(isNotUndefined); // User[]
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is not `undefined`, otherwise `false`.
+ */
+export declare function isNotUndefined<T>(value: T | undefined): value is T;
+//# sourceMappingURL=undefined.d.ts.map

package/dist/predicates/undefined.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undefined.d.ts","sourceRoot":"","sources":["../../src/predicates/undefined.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,KAAK,IAAI,SAAS,CAEvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAElE"}

package/dist/predicates/undefined.js

@@ -0,0 +1,33 @@
+/**
+ * Checks if a value is `undefined`. `null` is not considered `undefined`; use {@link isNil} to
+ * check for both.
+ *
+ * @example
+ * ```ts
+ * isUndefined(undefined); // true
+ * isUndefined(null); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is `undefined`, otherwise `false`.
+ */
+export function isUndefined(value) {
+    return value === undefined;
+}
+/**
+ * Checks if a value is not `undefined`, narrowing `undefined` out of its type. `null` passes
+ * this check; use {@link isNotNil} to exclude both.
+ *
+ * @example
+ * ```ts
+ * const lookups = ids.map((id) => cache.get(id)); // (User | undefined)[]
+ * const cached = lookups.filter(isNotUndefined); // User[]
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is not `undefined`, otherwise `false`.
+ */
+export function isNotUndefined(value) {
+    return value !== undefined;
+}
+//# sourceMappingURL=undefined.js.map

package/dist/predicates/undefined.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undefined.js","sourceRoot":"","sources":["../../src/predicates/undefined.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAI,KAAoB;IACjD,OAAO,KAAK,KAAK,SAAS,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAI,KAAoB;IACpD,OAAO,KAAK,KAAK,SAAS,CAAC;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@cult-frog/primitives",
+  "version": "0.1.0",
+  "description": "Small, dependency-free TypeScript type guards and callback helpers",
+  "license": "MIT",
+  "author": "Quin Partridge",
+  "keywords": [
+    "primitives",
+    "utilities",
+    "typescript",
+    "type-guards",
+    "predicates"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CapnQwan/cult-frog-primitives-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CapnQwan/cult-frog-primitives-js/issues"
+  },
+  "homepage": "https://github.com/CapnQwan/cult-frog-primitives-js#readme",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js}": [
+      "biome check --write --error-on-warnings --no-errors-on-unmatched"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.13",
+    "@cult-frog/tooling": "^0.1.2",
+    "@types/node": "^22.20.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.5.1",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "check": "biome check . --error-on-warnings",
+    "check:ci": "biome ci . --error-on-warnings",
+    "fix": "biome check . --write"
+  }
+}

package/src/callbacks/constant.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { constant } from './constant.js';
+
+describe('constant', () => {
+  it('returns a function that returns the given value', () => {
+    expect(constant('hello')()).toBe('hello');
+  });
+
+  it('returns the same value on every call', () => {
+    const getValue = constant(42);
+
+    expect(getValue()).toBe(42);
+    expect(getValue()).toBe(42);
+  });
+
+  it('returns the same object reference without copying', () => {
+    const value = { id: 1 };
+
+    expect(constant(value)()).toBe(value);
+  });
+
+  it.each([null, undefined, 0, '', false])('returns falsy value %s as-is', (value) => {
+    expect(constant(value)()).toBe(value);
+  });
+
+  it('preserves the value type', () => {
+    expectTypeOf(constant('hello')).toEqualTypeOf<() => string>();
+    expectTypeOf(constant({ id: 1 })).returns.toEqualTypeOf<{ id: number }>();
+  });
+});

package/src/callbacks/constant.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a function that always returns the given value.
+ *
+ * Useful when an API expects a callback or factory but you already have the value, e.g. a
+ * default provider or a stubbed dependency in tests.
+ *
+ * The same value is returned on every call; objects are not copied.
+ *
+ * @example
+ * ```ts
+ * const getDefaultName = constant('anonymous');
+ * getDefaultName(); // 'anonymous'
+ *
+ * const names = users.map((user) => user.name ?? getDefaultName());
+ * ```
+ *
+ * @param value - The value the returned function should produce.
+ * @returns A function that returns `value` every time it is called.
+ */
+export function constant<T>(value: T): () => T {
+  return () => value;
+}

package/src/callbacks/identity.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { identity } from './identity.js';
+
+describe('identity', () => {
+  it.each([1, 'text', true, null, undefined, 0, ''])('returns %s unchanged', (value) => {
+    expect(identity(value)).toBe(value);
+  });
+
+  it('returns the same object reference', () => {
+    const value = { id: 1 };
+
+    expect(identity(value)).toBe(value);
+  });
+
+  it('works as a default transform', () => {
+    expect([1, 2, 3].map(identity)).toEqual([1, 2, 3]);
+  });
+
+  it('preserves the value type', () => {
+    expectTypeOf(identity('text')).toEqualTypeOf<string>();
+    expectTypeOf(identity({ id: 1 })).toEqualTypeOf<{ id: number }>();
+  });
+});

package/src/callbacks/identity.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns the value it is given, unchanged.
+ *
+ * Useful as a default transform or a pass-through callback, so callers don't need to branch on
+ * whether a transform was provided.
+ *
+ * @example
+ * ```ts
+ * function formatAll<T>(items: T[], format: (item: T) => T = identity): T[] {
+ *   return items.map(format);
+ * }
+ *
+ * formatAll([1, 2, 3]); // [1, 2, 3]
+ * ```
+ *
+ * @param value - The value to return.
+ * @returns `value`, unchanged.
+ */
+export function identity<T>(value: T): T {
+  return value;
+}

package/src/callbacks/index.ts

@@ -0,0 +1,4 @@
+export * from './constant.js';
+export * from './identity.js';
+export * from './noop.js';
+export * from './once.js';

package/src/callbacks/noop.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { noop } from './noop.js';
+
+describe('noop', () => {
+  it('returns undefined', () => {
+    expect(noop()).toBeUndefined();
+  });
+
+  it('can be used where a callback with arguments is expected', () => {
+    const onProgress: (percent: number) => void = noop;
+
+    expect(() => onProgress(50)).not.toThrow();
+  });
+
+  it('has a void return type', () => {
+    expectTypeOf(noop).toEqualTypeOf<() => void>();
+  });
+});

package/src/callbacks/noop.ts

@@ -0,0 +1,17 @@
+/**
+ * A function that does nothing and returns `undefined`.
+ *
+ * Useful as a default for optional callbacks, so callers can invoke them without checking
+ * whether one was provided. Using a shared `noop` also makes intent clearer than an inline
+ * `() => {}`.
+ *
+ * @example
+ * ```ts
+ * function load(onProgress: (percent: number) => void = noop) {
+ *   onProgress(50);
+ * }
+ * ```
+ */
+export function noop(): void {
+  return;
+}

package/src/callbacks/once.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
+
+import { once } from './once.js';
+
+describe('once', () => {
+  it('calls the wrapped function only once', () => {
+    const fn = vi.fn(() => 'result');
+    const wrapped = once(fn);
+
+    wrapped();
+    wrapped();
+    wrapped();
+
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('returns the first result on every call', () => {
+    let count = 0;
+    const wrapped = once(() => ++count);
+
+    expect(wrapped()).toBe(1);
+    expect(wrapped()).toBe(1);
+  });
+
+  it('passes arguments from the first call and ignores later ones', () => {
+    const fn = vi.fn((a: number, b: number) => a + b);
+    const wrapped = once(fn);
+
+    expect(wrapped(1, 2)).toBe(3);
+    expect(wrapped(10, 20)).toBe(3);
+    expect(fn).toHaveBeenCalledWith(1, 2);
+  });
+
+  it('caches undefined results without calling again', () => {
+    const fn = vi.fn(() => undefined);
+    const wrapped = once(fn);
+
+    wrapped();
+    wrapped();
+
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('forwards this to the wrapped function', () => {
+    const obj = {
+      value: 42,
+      get: once(function (this: { value: number }) {
+        return this.value;
+      }),
+    };
+
+    expect(obj.get()).toBe(42);
+  });
+
+  it('retries on the next call if the wrapped function throws', () => {
+    let attempts = 0;
+    const wrapped = once(() => {
+      attempts++;
+      if (attempts === 1) {
+        throw new Error('first attempt fails');
+      }
+      return 'ok';
+    });
+
+    expect(() => wrapped()).toThrow('first attempt fails');
+    expect(wrapped()).toBe('ok');
+    expect(wrapped()).toBe('ok');
+    expect(attempts).toBe(2);
+  });
+
+  it('runs once in total when used on a shared prototype', () => {
+    class Counter {
+      static calls = 0;
+
+      init(): number {
+        return ++Counter.calls;
+      }
+    }
+    Counter.prototype.init = once(Counter.prototype.init);
+
+    new Counter().init();
+    new Counter().init();
+
+    expect(Counter.calls).toBe(1);
+  });
+
+  it('preserves the parameter and return types', () => {
+    const wrapped = once((a: number, b: string) => `${a}${b}`);
+
+    expectTypeOf(wrapped).parameters.toEqualTypeOf<[number, string]>();
+    expectTypeOf(wrapped).returns.toEqualTypeOf<string>();
+  });
+});

package/src/callbacks/once.ts

@@ -0,0 +1,41 @@
+/**
+ * Wraps a function so it runs at most once. Later calls return the result of the first call.
+ *
+ * Useful for lazy initialisation and for guarding side effects that must only happen once,
+ * such as setup, teardown or one-time warnings.
+ *
+ * - Arguments passed after the first successful call are ignored.
+ * - `this` is forwarded to `fn`, so the wrapper can be used as a method.
+ * - If `fn` throws, nothing is cached and the next call tries again.
+ * - After a successful call the reference to `fn` is released.
+ * - When used as a method on a shared prototype, `fn` runs once in total, not once per instance.
+ *
+ * @example
+ * ```ts
+ * const init = once(() => {
+ *   console.log('initialising');
+ *   return createClient();
+ * });
+ *
+ * init(); // logs 'initialising' and returns the client
+ * init(); // returns the same client without logging
+ * ```
+ *
+ * @param fn - The function to wrap.
+ * @returns A function with the same signature as `fn` that only invokes it once.
+ */
+export function once<This, Args extends unknown[], R>(
+  fn: (this: This, ...args: Args) => R
+): (this: This, ...args: Args) => R {
+  let pending: ((this: This, ...args: Args) => R) | undefined = fn;
+  let result: R;
+
+  return function (this: This, ...args: Args): R {
+    if (pending) {
+      result = pending.apply(this, args);
+      pending = undefined;
+    }
+
+    return result;
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './callbacks/index.js';
+export * from './predicates/index.js';

package/src/predicates/index.ts

@@ -0,0 +1,6 @@
+export * from './nil.js';
+export * from './null.js';
+export * from './number.js';
+export * from './record.js';
+export * from './string.js';
+export * from './undefined.js';

package/src/predicates/nil.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isNil, isNotNil } from './nil.js';
+
+const nilValues = [null, undefined];
+const nonNilValues = [0, '', false, Number.NaN, [], {}, 'text', 1];
+
+describe('isNil', () => {
+  it.each(nilValues)('returns true for %s', (value) => {
+    expect(isNil(value)).toBe(true);
+  });
+
+  it.each(nonNilValues)('returns false for %s', (value) => {
+    expect(isNil(value)).toBe(false);
+  });
+
+  it('narrows to null | undefined', () => {
+    const value = 'text' as string | null | undefined;
+
+    if (isNil(value)) {
+      expectTypeOf(value).toEqualTypeOf<null | undefined>();
+    } else {
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+});
+
+describe('isNotNil', () => {
+  it.each(nilValues)('returns false for %s', (value) => {
+    expect(isNotNil(value)).toBe(false);
+  });
+
+  it.each(nonNilValues)('returns true for %s', (value) => {
+    expect(isNotNil(value)).toBe(true);
+  });
+
+  it('removes null and undefined in filter while keeping falsy values', () => {
+    const result = [1, null, 0, undefined, 2].filter(isNotNil);
+
+    expect(result).toEqual([1, 0, 2]);
+    expectTypeOf(result).toEqualTypeOf<number[]>();
+  });
+});

package/src/predicates/nil.ts

@@ -0,0 +1,35 @@
+/**
+ * Checks if a value is `null` or `undefined`.
+ *
+ * @example
+ * ```ts
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is `null` or `undefined`, otherwise `false`.
+ */
+export function isNil<T>(value: T | null | undefined): value is null | undefined {
+  return value == null;
+}
+
+/**
+ * Checks if a value is neither `null` nor `undefined`, narrowing it to its non-nullable type.
+ *
+ * Unlike a truthiness check, falsy values such as `0`, `''` and `false` are kept.
+ *
+ * @example
+ * ```ts
+ * const values = [1, null, 0, undefined, 2];
+ * const present = values.filter(isNotNil); // number[]: [1, 0, 2]
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is not `null` or `undefined`, otherwise `false`.
+ */
+export function isNotNil<T>(value: T | null | undefined): value is T {
+  return value != null;
+}

package/src/predicates/null.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isNotNull, isNull } from './null.js';
+
+const nonNullValues = [undefined, 0, '', false, {}, 'text'];
+
+describe('isNull', () => {
+  it('returns true for null', () => {
+    expect(isNull(null)).toBe(true);
+  });
+
+  it.each(nonNullValues)('returns false for %s', (value) => {
+    expect(isNull(value)).toBe(false);
+  });
+
+  it('narrows to null', () => {
+    const value = 'text' as string | null;
+
+    if (isNull(value)) {
+      expectTypeOf(value).toEqualTypeOf<null>();
+    } else {
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+});
+
+describe('isNotNull', () => {
+  it('returns false for null', () => {
+    expect(isNotNull(null)).toBe(false);
+  });
+
+  it.each(nonNullValues)('returns true for %s', (value) => {
+    expect(isNotNull(value)).toBe(true);
+  });
+
+  it('removes null in filter but keeps undefined', () => {
+    const result = [1, null, undefined].filter(isNotNull);
+
+    expect(result).toEqual([1, undefined]);
+    expectTypeOf(result).toEqualTypeOf<(number | undefined)[]>();
+  });
+});