@cult-frog/primitives 0.1.0

package/src/predicates/null.ts

@@ -0,0 +1,33 @@
+/**
+ * Checks if a value is `null`. `undefined` is not considered `null`; use {@link isNil} to check
+ * for both.
+ *
+ * @example
+ * ```ts
+ * isNull(null); // true
+ * isNull(undefined); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is `null`, otherwise `false`.
+ */
+export function isNull<T>(value: T | null): value is null {
+  return value === null;
+}
+
+/**
+ * Checks if a value is not `null`, narrowing `null` out of its type. `undefined` passes this
+ * check; use {@link isNotNil} to exclude both.
+ *
+ * @example
+ * ```ts
+ * const rows: (Row | null)[] = await fetchRows();
+ * const found = rows.filter(isNotNull); // Row[]
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is not `null`, otherwise `false`.
+ */
+export function isNotNull<T>(value: T | null): value is T {
+  return value !== null;
+}

package/src/predicates/number.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isNumber } from './number.js';
+
+describe('isNumber', () => {
+  it.each([0, -0, 1, -1, 1.5, Number.MAX_SAFE_INTEGER, Number.MIN_VALUE])(
+    'returns true for %s',
+    (value) => {
+      expect(isNumber(value)).toBe(true);
+    }
+  );
+
+  it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
+    'returns false for non-finite %s',
+    (value) => {
+      expect(isNumber(value)).toBe(false);
+    }
+  );
+
+  it.each(['42', '', null, undefined, true, 10n, {}, []])(
+    'returns false for non-number %s without coercion',
+    (value) => {
+      expect(isNumber(value)).toBe(false);
+    }
+  );
+
+  it('returns false for Number wrapper objects', () => {
+    expect(isNumber(new Number(1))).toBe(false);
+  });
+
+  it('narrows unknown to number', () => {
+    const value: unknown = 1;
+
+    if (isNumber(value)) {
+      expectTypeOf(value).toEqualTypeOf<number>();
+    }
+  });
+});

package/src/predicates/number.ts

@@ -0,0 +1,21 @@
+/**
+ * Checks if a value is a finite number.
+ *
+ * `NaN`, `Infinity` and `-Infinity` are rejected, as are numeric strings such as `'42'`; no
+ * coercion is performed.
+ *
+ * @example
+ * ```ts
+ * isNumber(42); // true
+ * isNumber(-1.5); // true
+ * isNumber(NaN); // false
+ * isNumber(Infinity); // false
+ * isNumber('42'); // false
+ * ```
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is a finite number, otherwise `false`.
+ */
+export function isNumber(value: unknown): value is number {
+  return Number.isFinite(value);
+}

package/src/predicates/record.test.ts

@@ -0,0 +1,107 @@
+/// <reference types="node" />
+import { runInNewContext } from 'node:vm';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { hasProperty, isNotRecord, isRecord } from './record.js';
+
+class Example {
+  value = 1;
+}
+
+const records = [{}, { id: 1 }, Object.create(null), JSON.parse('{"a":1}')];
+const nonRecords = [
+  null,
+  undefined,
+  0,
+  'text',
+  true,
+  [],
+  new Date(),
+  new Map(),
+  new Set(),
+  /regex/,
+  new Example(),
+  Promise.resolve(),
+  () => {},
+];
+
+describe('isRecord', () => {
+  it.each(records)('returns true for plain object %o', (value) => {
+    expect(isRecord(value)).toBe(true);
+  });
+
+  it.each(nonRecords)('returns false for %o', (value) => {
+    expect(isRecord(value)).toBe(false);
+  });
+
+  it('returns false for objects from another realm', () => {
+    expect(isRecord(runInNewContext('({})'))).toBe(false);
+  });
+
+  it('narrows unknown to Record<PropertyKey, unknown>', () => {
+    const value: unknown = {};
+
+    if (isRecord(value)) {
+      expectTypeOf(value).toEqualTypeOf<Record<PropertyKey, unknown>>();
+    }
+  });
+});
+
+describe('isNotRecord', () => {
+  it.each(records)('returns false for plain object %o', (value) => {
+    expect(isNotRecord(value)).toBe(false);
+  });
+
+  it.each(nonRecords)('returns true for %o', (value) => {
+    expect(isNotRecord(value)).toBe(true);
+  });
+
+  it('narrows the record out of a union', () => {
+    const value = 'text' as string | Record<string, unknown>;
+
+    if (isNotRecord(value)) {
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+});
+
+describe('hasProperty', () => {
+  it('returns true for own properties', () => {
+    expect(hasProperty({ id: 1 }, 'id')).toBe(true);
+  });
+
+  it('returns true for own properties holding undefined', () => {
+    expect(hasProperty({ id: undefined }, 'id')).toBe(true);
+  });
+
+  it('returns false for missing properties', () => {
+    expect(hasProperty({ id: 1 }, 'name')).toBe(false);
+  });
+
+  it('returns false for inherited properties', () => {
+    expect(hasProperty({}, 'toString')).toBe(false);
+    expect(hasProperty(Object.create({ inherited: true }), 'inherited')).toBe(false);
+  });
+
+  it('supports symbol and numeric keys', () => {
+    const key = Symbol('key');
+
+    expect(hasProperty({ [key]: 1 }, key)).toBe(true);
+    expect(hasProperty(['a'], 0)).toBe(true);
+  });
+
+  it('works on objects without a prototype', () => {
+    const value = Object.create(null) as object;
+    Object.assign(value, { id: 1 });
+
+    expect(hasProperty(value, 'id')).toBe(true);
+  });
+
+  it('narrows the object so the property can be read', () => {
+    const value: object = { id: 1 };
+
+    if (hasProperty(value, 'id')) {
+      expectTypeOf(value.id).toEqualTypeOf<unknown>();
+    }
+  });
+});

package/src/predicates/record.ts

@@ -0,0 +1,74 @@
+/**
+ * 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: unknown): value is Record<PropertyKey, unknown> {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const prototype: unknown = 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<T>(value: T): value is Exclude<T, Record<PropertyKey, unknown>> {
+  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<K extends PropertyKey>(
+  value: object,
+  key: K
+): value is Record<K, unknown> {
+  return Object.hasOwn(value, key);
+}

package/src/predicates/string.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isString } from './string.js';
+
+describe('isString', () => {
+  it.each(['', 'text', `template`])('returns true for %j', (value) => {
+    expect(isString(value)).toBe(true);
+  });
+
+  it.each([0, null, undefined, true, {}, [], Symbol('s')])('returns false for %s', (value) => {
+    expect(isString(value)).toBe(false);
+  });
+
+  it('returns false for String wrapper objects', () => {
+    expect(isString(new String('text'))).toBe(false);
+  });
+
+  it('narrows unknown to string', () => {
+    const value: unknown = 'text';
+
+    if (isString(value)) {
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+});

package/src/predicates/string.ts

@@ -0,0 +1,16 @@
+/**
+ * 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: unknown): value is string {
+  return typeof value === 'string';
+}

package/src/predicates/undefined.test.ts

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

package/src/predicates/undefined.ts

@@ -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<T>(value: T | undefined): value is undefined {
+  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<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}