ts-data-forge 14.6.2 → 14.6.3

package/dist/functional/ternary-result/impl/ternary-result-unwrap-warn-throw.mjs

@@ -1,30 +1,30 @@
 import { unknownToString } from '../../../others/index.mjs';
 import { isWarn } from './ternary-result-is-warn.mjs';
 import { variantName } from './variant-name.mjs';
-/**
- * Returns the Warn value or throws if the result is not Warn.
- *
- * @example
- *
- * ```ts
- * const warnValue = TernaryResult.warn('pending', 'check logs');
- *
- * assert.strictEqual(TernaryResult.unwrapWarnThrow(warnValue), 'check logs');
- *
- * assert.throws(
- *   () => TernaryResult.unwrapWarnThrow(TernaryResult.err('err')),
- *   /Expected Warn/u,
- * );
- * ```
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const unwrapWarnThrow = (result, toStr = unknownToString) => {
     if (isWarn(result)) {
-        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+
         return result.warning;
     }
     const variant = variantName(result.$$tag);
     throw new Error(`Expected Warn but got ${variant}: ${toStr(
-    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+
     result.value)}`);
 };
 //# sourceMappingURL=ternary-result-unwrap-warn-throw.mjs.map

package/dist/functional/ternary-result/impl/ternary-result-unwrap-warn.mjs

@@ -1,21 +1,21 @@
 import { isWarn } from './ternary-result-is-warn.mjs';
-/**
- * Safely unwraps the Warn value.
- *
- * @example
- *
- * ```ts
- * const warnValue = TernaryResult.warn('ok', 'careful');
- *
- * const okValue = TernaryResult.ok('ok');
- *
- * assert.strictEqual(TernaryResult.unwrapWarn(warnValue), 'careful');
- *
- * // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
- * assert.strictEqual(TernaryResult.unwrapWarn(okValue), undefined);
- * ```
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const unwrapWarn = (result) => 
-// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+
 isWarn(result) ? result.warning : undefined;
 //# sourceMappingURL=ternary-result-unwrap-warn.mjs.map

package/dist/functional/ternary-result/impl/ternary-result-warn.mjs

@@ -1,20 +1,20 @@
 import { WarnTypeTagName } from './tag.mjs';
-/**
- * Creates a `TernaryResult.Warn` containing the provided success value and
- * warning.
- *
- * @example
- *
- * ```ts
- * const caution = TernaryResult.warn({ id: 1 }, 'Needs review');
- *
- * assert.deepStrictEqual(caution, {
- *   $$tag: 'ts-data-forge::Result.warn',
- *   value: { id: 1 },
- *   warning: 'Needs review',
- * });
- * ```
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const warn = (value, warning) => ({
     $$tag: WarnTypeTagName,
     value,

package/dist/functional/ternary-result/impl/ternary-result-zip.mjs

@@ -2,37 +2,37 @@ import { isErr } from './ternary-result-is-err.mjs';
 import { isWarn } from './ternary-result-is-warn.mjs';
 import { ok } from './ternary-result-ok.mjs';
 import { warn } from './ternary-result-warn.mjs';
-/**
- * Combines two `TernaryResult`s, prioritising Err over Warn over Ok.
- *
- * @example
- *
- * ```ts
- * const okPair = TernaryResult.zip(
- *   TernaryResult.ok('left'),
- *   TernaryResult.ok(1),
- * );
- *
- * const warnPair = TernaryResult.zip(
- *   TernaryResult.warn('left', 'warn'),
- *   TernaryResult.ok(1),
- * );
- *
- * const errPair = TernaryResult.zip(
- *   TernaryResult.ok('left'),
- *   TernaryResult.err('err'),
- * );
- *
- * assert.deepStrictEqual(okPair, TernaryResult.ok(['left', 1] as const));
- *
- * assert.deepStrictEqual(
- *   warnPair,
- *   TernaryResult.warn(['left', 1] as const, 'warn'),
- * );
- *
- * assert.deepStrictEqual(errPair, TernaryResult.err('err'));
- * ```
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const zip = (resultA, resultB) => {
     if (isErr(resultA)) {
         return resultA;

package/dist/functional/ternary-result/impl/variant-name.mjs

@@ -1,5 +1,5 @@
 import { ErrTypeTagName, OkTypeTagName, WarnTypeTagName } from './tag.mjs';
-/** @internal Returns the human readable variant label for the given tag. */
+
 export const variantName = (tag) => {
     switch (tag) {
         case OkTypeTagName:

package/dist/guard/has-key.mjs

@@ -1,43 +1,43 @@
-/**
- * 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
- *
- * @example
- *
- * ```ts
- * const maybeUser: Readonly<{ id?: number; name?: string }> = {
- *   id: 42,
- * } as const;
- *
- * if (hasKey(maybeUser, 'id')) {
- *   // `maybeUser` is now known to have an `id` property.
- *   assert.isTrue(maybeUser.id === 42);
- * } else {
- *   assert.fail();
- * }
- * ```
- *
- * @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
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const hasKey = (obj, key) => Object.hasOwn(obj, key);
 //# sourceMappingURL=has-key.mjs.map

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

@@ -1,39 +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.
- *
- * **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
- *
- * @example
- *
- * ```ts
- * const words: readonly (string | undefined)[] = [
- *   'Ada',
- *   undefined,
- *   '',
- *   'Lovelace',
- * ] as const;
- *
- * const nonEmpty = words.filter(isNonEmptyString);
- *
- * 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 const isNonEmptyString = (s) => typeof s === 'string' && s.length > 0;
 //# sourceMappingURL=is-non-empty-string.mjs.map

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

@@ -1,36 +1,36 @@
-/**
- * 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
- * record-oriented narrowing that excludes arrays, use `isRecord()` instead.
- *
- * @example
- *
- * ```ts
- * const mixed: readonly unknown[] = [{ id: 1 }, null, 'Ada'] as const;
- *
- * const objects = mixed.filter(isNonNullObject);
- *
- * 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 record-oriented type narrowing (excludes arrays)
- */
-// eslint-disable-next-line @typescript-eslint/no-restricted-types
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const isNonNullObject = (u) => typeof u === 'object' && u !== null;
 //# sourceMappingURL=is-non-null-object.mjs.map

package/dist/guard/is-primitive.mjs

@@ -1,35 +1,35 @@
 
-/**
- * Type guard that checks if a value is a primitive type.
- *
- * This function identifies JavaScript primitive types, which are immutable data
- * types that are not objects. The primitive types are: `string`, `number`,
- * `boolean`, `undefined`, `symbol`, `bigint`, and `null`.
- *
- * **Important Note:** Although `null` has `typeof null === "object"` due to a
- * historical JavaScript quirk, this function correctly identifies `null` as a
- * primitive value.
- *
- * **Type Narrowing Behavior:**
- *
- * - Narrows the input type to `Primitive` (union of all primitive types)
- * - Excludes object types, arrays, functions, and other non-primitive values
- * - Includes `null` despite its misleading `typeof` result
- *
- * @example
- *
- * ```ts
- * const values: readonly unknown[] = [42, 'Ada', null, { id: 1 }] as const;
- *
- * const primitives = values.filter(isPrimitive);
- *
- * assert.deepStrictEqual(primitives, [42, 'Ada', null]);
- * ```
- *
- * @param u - The value to check
- * @returns `true` if `u` is a primitive type, `false` otherwise. When `true`,
- *   TypeScript narrows the type to `Primitive`.
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const isPrimitive = (u) => {
     switch (typeof u) {
         case 'string':

package/dist/guard/is-record.mjs

@@ -1,90 +1,90 @@
 import { isNonNullObject } from './is-non-null-object.mjs';
-/**
- * Type guard that checks if a value is a record — a non-null, non-array
- * object — and narrows it to `UnknownRecord` (= `ReadonlyRecord<string,
- * unknown>`).
- *
- * This function is designed to be combined with {@link hasKey} to probe
- * values of type `unknown` (e.g. parsed JSON, caught errors, external data)
- * in a type-safe way: `if (isRecord(u) && hasKey(u, 'some-key')) { ... }`.
- *
- * **Type Narrowing Behavior:**
- *
- * - Narrows `unknown` to `UnknownRecord` (= `ReadonlyRecord<string, unknown>`)
- * - Excludes `null`, `undefined`, primitives, and functions
- * - Excludes arrays: arrays have no string index signature, so they are not
- *   assignable to `UnknownRecord`; admitting them at runtime would be
- *   inconsistent with the narrowed type
- * - Returns `true` for every other non-null object, including dictionary
- *   objects created with `Object.create(null)` and instances such as `Date`,
- *   `RegExp`, `Map`, `Set`, `Error`, and user-defined classes
- *
- * **Why non-plain objects are included:** since every property of
- * `UnknownRecord` is typed `unknown`, reading properties from any object
- * through this narrowing is type-safe, and `hasKey` (backed by
- * `Object.hasOwn`) answers own-property questions correctly on any object
- * (e.g. `Map` entries are not own properties, so `hasKey` correctly returns
- * `false` for them). Restricting the guard to plain objects would require
- * prototype checks that misjudge cross-realm objects and would prevent
- * probing useful instances such as `Error` subclasses.
- *
- * **Implementation:** `isNonNullObject(u) && !Array.isArray(u)`.
- *
- * @example
- *
- * ```ts
- * const entries: readonly unknown[] = [
- *   { id: 1 },
- *   [1, 2],
- *   'str',
- *   0,
- *   null,
- * ] as const;
- *
- * const records = entries.filter(isRecord);
- *
- * assert.deepStrictEqual(records, [{ id: 1 }]);
- * ```
- *
- * @param u - The value to check
- * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
- *   When `true`, TypeScript narrows the type to `UnknownRecord`.
- * @see {@link isNonNullObject} - For checking any non-null object (includes arrays)
- * @see {@link hasKey} - For checking if a record has specific keys
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const isRecord = (u) => isNonNullObject(u) && !Array.isArray(u);
-/**
- * Type guard that checks if a value is a mutable record.
- *
- * This function has the same runtime behavior as {@link isRecord} (non-null,
- * non-array object check), but narrows the type to `MutableRecord<string,
- * unknown>`, which is useful when you need to add or overwrite properties on
- * the narrowed object.
- *
- * **Type Narrowing Behavior:**
- *
- * - Narrows `unknown` to `MutableRecord<string, unknown>`
- * - Excludes `null`, `undefined`, primitives, functions, and arrays
- * - Returns `true` for every other non-null object (see {@link isRecord} for
- *   details on non-plain objects such as `Date`, `Map`, and `Set`)
- *
- * **Implementation:** This is a type alias for {@link isRecord}.
- *
- * @example
- *
- * ```ts
- * const obj: unknown = { foo: 1 } as const;
- *
- * if (isMutableRecord(obj)) {
- *   obj['bar'] = 2; // Safe: obj is now known to be a mutable record
- * }
- * ```
- *
- * @param u - The value to check
- * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
- *   When `true`, TypeScript narrows the type to `MutableRecord<string,
- *   unknown>`.
- * @see {@link isRecord} - For the underlying implementation and more details
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const isMutableRecord = isRecord;
 //# sourceMappingURL=is-record.mjs.map