ts-data-forge 14.7.0 → 14.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "14.7.0",
+  "version": "14.8.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -37,28 +37,28 @@
   ],
   "dependencies": {
     "@sindresorhus/is": "^8.1.0",
-    "ts-std-forge": "^0.5.0",
+    "ts-std-forge": "^0.5.1",
     "ts-type-forge": "~9.2.2"
   },
   "devDependencies": {
     "@emotion/react": "11.14.0",
     "@emotion/styled": "11.14.1",
     "@mui/material": "9.4.0",
-    "@types/react": "19.2.18",
-    "@vitest/browser-playwright": "4.1.11",
-    "eslint-config-typed": "5.11.6",
-    "eslint-plugin-ts-fortress": "1.2.2",
-    "eslint-plugin-ts-type-forge": "0.8.3",
-    "immer": "11.1.18",
-    "playwright": "1.62.1",
-    "prettier": "3.9.6",
+    "@types/react": "19.3.0",
+    "@vitest/browser-playwright": "5.0.3",
+    "eslint-config-typed": "5.19.0",
+    "eslint-plugin-ts-fortress": "1.3.4",
+    "eslint-plugin-ts-type-forge": "0.8.9",
+    "immer": "11.1.21",
+    "playwright": "1.64.0",
+    "prettier": "3.9.9",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
-    "react": "19.2.8",
-    "ts-repo-utils": "10.6.1",
+    "react": "19.3.0",
+    "ts-repo-utils": "10.7.1",
     "typedoc": "0.28.20",
     "typedoc-github-theme": "0.4.0",
-    "vite": "8.2.2"
+    "vite": "8.3.3"
   },
   "peerDependencies": {
     "typescript": ">=4.8"
@@ -73,30 +73,31 @@
   },
   "scripts": {
     "build": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts",
-    "build:min": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts --skip-check",
     "check:ext": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/check-ext.mts",
+    "check:lint": "node ../../tools/scripts/cmd/assert-deps-built.mts && oxlint . && eslint .",
+    "check:test": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest:node run",
+    "check:test:browser": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest --project='Browser' run",
+    "check:test:cov": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest:node run --coverage",
+    "check:types": "node ../../tools/scripts/cmd/assert-deps-built.mts && node ../../node_modules/typescript-native/bin/tsc --noEmit",
     "doc": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/gen-docs.mts",
-    "doc:embed": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples.mts",
-    "doc:embed:jsdoc": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples-in-jsdoc.mts",
     "doc:preview": "vite preview --config ./configs/vite.doc.config.mts",
-    "doc:watch": "typedoc --options ./configs/typedoc.config.mjs --watch",
-    "fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
-    "fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
-    "fmt:full": "pnpm run z:prettier .",
-    "gen:branded-number": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/gen-branded-number/generate.mts && pnpm run doc:embed:jsdoc && pnpm run z:prettier 'src/number/branded-types/*.mts' 'src/number/enum/*.mts'",
-    "gi": "run-s gi:src fmt",
-    "gi:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json scripts/cmd/gen-index.mts",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "test": "pnpm run z:vitest:node run",
-    "test:browser": "pnpm run z:vitest --project='Browser' run",
-    "test:cov": "pnpm run z:vitest:node run --coverage",
+    "fix:fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
+    "fix:fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
+    "fix:fmt:full": "pnpm run z:prettier .",
+    "fix:lint": "node ../../tools/scripts/cmd/assert-deps-built.mts && oxlint . --fix && eslint . --fix",
+    "fmt": "pnpm run fix:fmt",
+    "gen": "run-s gen:index gen:branded-number gen:readme gen:jsdoc",
+    "gen:branded-number": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/gen-branded-number/generate.mts && pnpm run gen:jsdoc && pnpm run z:prettier 'src/number/branded-types/*.mts' 'src/number/enum/*.mts'",
+    "gen:index": "run-s gen:index:src fix:fmt",
+    "gen:index:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/gen-index-ts.mts ./src --index-ext .mts --export-ext .mjs --target-ext .mts --exclude entry-point.mts --preserve 'array/index.mts' --preserve 'functional/index.mts'",
+    "gen:jsdoc": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples-in-jsdoc.mts",
+    "gen:readme": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples.mts",
+    "test": "pnpm run check:test",
     "test:cov:ui": "vite preview --outDir ./coverage",
     "test:ui": "pnpm run z:vitest:node --ui",
-    "testw": "pnpm run z:vitest:node watch",
-    "tsc": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
-    "tscw": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
-    "type-check": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "watch:doc": "typedoc --options ./configs/typedoc.config.mjs --watch",
+    "watch:test": "pnpm run z:vitest:node watch",
+    "watch:types": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
     "z:prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --ignore-path ../../.gitignore --ignore-unknown --no-error-on-unmatched-pattern --write",
     "z:vitest": "vitest --config ./configs/vitest.config.mts",
     "z:vitest:node": "pnpm run z:vitest --project='Node.js'"

package/src/array/impl/array-utils-creation.mts

@@ -1,27 +1,26 @@
-import {
-  type BoolOr,
-  type FixedLengthArray,
-  type FixedLengthTuple,
-  type Index,
-  type IsUnion,
-  type List,
-  type Min,
-  type NonEmptyArray,
-  type NonZeroSafeIntWithSmallInt,
-  type PositiveSafeIntWithSmallInt,
-  type RelaxedExclude,
-  type SafeInt,
-  type SafeIntWithSmallInt,
-  type SafeUint,
-  type SafeUintWithSmallInt,
-  type Seq,
-  type SmallUint,
-  type StructuralPrefixLength,
-  type SupportedLength,
+import type {
+  BoolOr,
+  FixedLengthArray,
+  FixedLengthTuple,
+  Index,
+  IsUnion,
+  List,
+  Min,
+  NonEmptyArray,
+  NonZeroSafeIntWithSmallInt,
+  RelaxedExclude,
+  SafeInt,
+  SafeIntWithSmallInt,
+  SafeUint,
+  SafeUintWithSmallInt,
+  Seq,
+  SmallUint,
+  StructuralPrefixLength,
+  SupportedLength,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { range as rangeIterator } from '../../iterator/index.mjs';
-import { type SizeType } from '../../types.mjs';
+import type { SizeType } from '../../types.mjs';
 
 /**
  * Creates an array of zeros with the specified length.
@@ -216,7 +215,10 @@ export function range<S extends SmallUint, E extends SmallUint>(
 export function range(
   start: SafeUintWithSmallInt,
   end: SafeUintWithSmallInt,
-  step?: PositiveSafeIntWithSmallInt,
+  // Every value lies between `start` and `end`, so a negative step yields
+  // non-negative numbers too.
+
+  step?: NonZeroSafeIntWithSmallInt,
 ): readonly SafeUint[];
 
 export function range(

package/src/array/impl/array-utils-creation.test.mts

@@ -1,18 +1,13 @@
-import {
-  type FixedLengthTuple,
-  type SafeInt,
-  type SafeUint,
-  type SmallUint,
+import type {
+  FixedLengthTuple,
+  SafeInt,
+  SafeUint,
+  SmallUint,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { range as rangeIterator } from '../../iterator/index.mjs';
-import {
-  asNonZeroSafeInt,
-  asSafeInt,
-  asSafeUint,
-  asUint32,
-} from '../../number/index.mjs';
-import { type SizeType } from '../../types.mjs';
+import { asNonZeroSafeInt, asSafeUint, asUint32 } from '../../number/index.mjs';
+import type { SizeType } from '../../types.mjs';
 import {
   copy,
   create,
@@ -380,18 +375,26 @@ describe('Arr creations', () => {
       const result = range(5, 0, -1);
 
       assert.deepStrictEqual(result, [
-        asSafeInt(5),
-        asSafeInt(4),
-        asSafeInt(3),
-        asSafeInt(2),
-        asSafeInt(1),
+        asSafeUint(5),
+        asSafeUint(4),
+        asSafeUint(3),
+        asSafeUint(2),
+        asSafeUint(1),
       ]);
     });
 
+    test('a negative step from non-negative bounds gives SafeUint', () => {
+      const result = range(asSafeUint(5), asSafeUint(1), asNonZeroSafeInt(-2));
+
+      expectType<typeof result, readonly SafeUint[]>('=');
+
+      assert.deepStrictEqual(result, [asSafeUint(5), asSafeUint(3)]);
+    });
+
     test('start > end, step < 0, not reaching end', () => {
       const result = range(5, 1, -2);
 
-      assert.deepStrictEqual(result, [asSafeInt(5), asSafeInt(3)]);
+      assert.deepStrictEqual(result, [asSafeUint(5), asSafeUint(3)]);
     });
 
     test('start < end, step < 0 (empty result)', () => {
@@ -419,12 +422,12 @@ describe('Arr creations', () => {
         asNonZeroSafeInt(step),
       );
 
-      expectType<typeof result, readonly SafeInt[]>('=');
+      expectType<typeof result, readonly SafeUint[]>('=');
 
       assert.deepStrictEqual(result, [
-        asSafeInt(1),
-        asSafeInt(2),
-        asSafeInt(3),
+        asSafeUint(1),
+        asSafeUint(2),
+        asSafeUint(3),
       ]);
     });
 

package/src/array/impl/array-utils-element-access.mts

@@ -1,10 +1,10 @@
-import { type NonEmptyTuple } from 'ts-type-forge';
+import type { NonEmptyTuple } from 'ts-type-forge';
 import { Optional, pipe } from '../../functional/index.mjs';
-import {
-  type ArgArrayIndexWithNegative,
-  type None,
-  type SizeType,
-  type Some,
+import type {
+  ArgArrayIndexWithNegative,
+  None,
+  SizeType,
+  Some,
 } from '../../types.mjs';
 
 /**
@@ -58,7 +58,7 @@ const atImpl = <E,>(
   index: SizeType.ArgArrWithNegative,
 ): Optional<E> =>
   pipe(index < 0 ? array.length + index : index).map((normalizedIndex) =>
-    normalizedIndex < 0 || normalizedIndex >= array.length
+    normalizedIndex < 0 || array.length <= normalizedIndex
       ? Optional.none
       : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         Optional.some(array[normalizedIndex]!),

package/src/array/impl/array-utils-element-access.test.mts

@@ -1,8 +1,8 @@
-import { type NonEmptyTuple } from 'ts-type-forge';
+import type { NonEmptyTuple } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { Optional } from '../../functional/index.mjs';
 import { asInt32, asUint32 } from '../../number/index.mjs';
-import { type None, type Some } from '../../types.mjs';
+import type { None, Some } from '../../types.mjs';
 import { at, head, last } from './array-utils-element-access.mjs';
 
 describe('Arr element access', () => {

package/src/array/impl/array-utils-iterators.mts

@@ -1,5 +1,5 @@
 import { asUint32 } from '../../number/index.mjs';
-import { type SizeType } from '../../types.mjs';
+import type { SizeType } from '../../types.mjs';
 
 /**
  * Returns an iterator of `[index, value]` pairs for an array.

package/src/array/impl/array-utils-iterators.test.mts

@@ -1,4 +1,4 @@
-import { type Uint32 } from 'ts-type-forge';
+import type { Uint32 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { asUint32 } from '../../number/index.mjs';
 import { entries, indices, values } from './array-utils-iterators.mjs';

package/src/array/impl/array-utils-length-bounded-array-cast.mts

@@ -1,10 +1,10 @@
-import {
-  type BoundedLengthArray,
-  type FixedLengthArray,
-  type MaxLengthArray,
-  type MinLengthArray,
-  type NonEmptyArray,
-  type SupportedLength,
+import type {
+  BoundedLengthArray,
+  FixedLengthArray,
+  MaxLengthArray,
+  MinLengthArray,
+  NonEmptyArray,
+  SupportedLength,
 } from 'ts-type-forge';
 import {
   isBoundedLengthArray,
@@ -33,13 +33,21 @@ import {
  * const rgb = Arr.asFixedLengthArray(3, [255, 128, 0]);
  *
  * const atMost5: MaxLengthArray<5, number> = rgb; // OK (3 <= 5)
+ *
  * const red: number = rgb[0]; // OK — no `undefined`
  *
  * // curried version
  * const asRgb = Arr.asFixedLengthArray(3);
+ *
  * const green = asRgb([0, 255, 0]);
  *
- * // Arr.asFixedLengthArray(3, [255, 128]); // throws TypeError
+ * assert.deepStrictEqual(Array.from(atMost5), [255, 128, 0]);
+ *
+ * assert.strictEqual(red, 255);
+ *
+ * assert.deepStrictEqual(green, [0, 255, 0]);
+ *
+ * assert.throws(() => Arr.asFixedLengthArray(3, [255, 128]), TypeError);
  * ```
  *
  * @template Length - The exact number of elements.
@@ -110,13 +118,21 @@ const asFixedLengthArrayImpl = <E,>(
  * const history = Arr.asMinLengthArray(3, [0, 1, 2, 3]);
  *
  * const nonEmpty: MinLengthArray<1, number> = history; // OK (3 >= 1)
+ *
  * const first: number = history[0]; // OK — no `undefined`
  *
  * // curried version
  * const asHistory = Arr.asMinLengthArray(3);
+ *
  * const next = asHistory([4, 5, 6, 7]);
  *
- * // Arr.asMinLengthArray(3, [0]); // throws TypeError
+ * assert.deepStrictEqual(Array.from(nonEmpty), [0, 1, 2, 3]);
+ *
+ * assert.strictEqual(first, 0);
+ *
+ * assert.deepStrictEqual(next, [4, 5, 6, 7]);
+ *
+ * assert.throws(() => Arr.asMinLengthArray(3, [0]), TypeError);
  * ```
  *
  * @template MinLength - The minimum number of elements (inclusive).
@@ -188,9 +204,14 @@ const asMinLengthArrayImpl = <E,>(
  *
  * // curried version
  * const asTags = Arr.asMaxLengthArray(8);
+ *
  * const more = asTags(['d', 'e']);
  *
- * // Arr.asMaxLengthArray(2, ['a', 'b', 'c']); // throws TypeError
+ * assert.deepStrictEqual(Array.from(relaxed), ['a', 'b', 'c']);
+ *
+ * assert.deepStrictEqual(more, ['d', 'e']);
+ *
+ * assert.throws(() => Arr.asMaxLengthArray(2, ['a', 'b', 'c']), TypeError);
  * ```
  *
  * @template MaxLength - The maximum number of elements (inclusive).
@@ -264,9 +285,14 @@ const asMaxLengthArrayImpl = <E,>(
  *
  * // curried version
  * const asSelection = Arr.asBoundedLengthArray(1, 5);
+ *
  * const next = asSelection([4, 5]);
  *
- * // Arr.asBoundedLengthArray(1, 5, []); // throws TypeError
+ * assert.deepStrictEqual(Array.from(relaxed), [1, 2, 3]);
+ *
+ * assert.deepStrictEqual(next, [4, 5]);
+ *
+ * assert.throws(() => Arr.asBoundedLengthArray(1, 5, []), TypeError);
  * ```
  *
  * @template MinLength - The minimum number of elements (inclusive).
@@ -349,7 +375,9 @@ const asBoundedLengthArrayImpl = <E,>(
  *
  * const atMost5: MaxLengthArray<5, never> = nothing; // OK (0 <= 5)
  *
- * // Arr.asEmptyArray([1]); // throws TypeError
+ * assert.deepStrictEqual(Array.from(atMost5), []);
+ *
+ * assert.throws(() => Arr.asEmptyArray([1]), TypeError);
  * ```
  *
  * @template Xs - The input array type (tuple types are preserved).
@@ -387,7 +415,9 @@ export const asEmptyArray = <Xs extends readonly unknown[]>(
  *
  * const first: number = history[0]; // OK — no `undefined`
  *
- * // Arr.asNonEmptyArray([]); // throws TypeError
+ * assert.strictEqual(first, 0);
+ *
+ * assert.throws(() => Arr.asNonEmptyArray([]), TypeError);
  * ```
  *
  * @template Xs - The input array type (tuple types are preserved).

package/src/array/impl/array-utils-length-bounded-array-cast.test.mts

@@ -1,9 +1,9 @@
-import {
-  type BoundedLengthArray,
-  type FixedLengthArray,
-  type MaxLengthArray,
-  type MinLengthArray,
-  type NonEmptyArray,
+import type {
+  BoundedLengthArray,
+  FixedLengthArray,
+  MaxLengthArray,
+  MinLengthArray,
+  NonEmptyArray,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import {

package/src/array/impl/array-utils-length-bounded-array-guard.mts

@@ -1,9 +1,9 @@
-import {
-  type BoundedLengthArray,
-  type FixedLengthArray,
-  type MaxLengthArray,
-  type MinLengthArray,
-  type SupportedLength,
+import type {
+  BoundedLengthArray,
+  FixedLengthArray,
+  MaxLengthArray,
+  MinLengthArray,
+  SupportedLength,
 } from 'ts-type-forge';
 
 /**
@@ -38,9 +38,9 @@ import {
  *
  *   const nonEmpty: MinLengthArray<1, number> = input; // OK (3 >= 1)
  *
- *   assert.deepStrictEqual(history[0], 0);
+ *   assert.strictEqual(history[0], 0);
  *
- *   assert.deepStrictEqual(nonEmpty[0], 0);
+ *   assert.strictEqual(nonEmpty[0], 0);
  * }
  *
  * // curried version
@@ -122,9 +122,9 @@ const hasMinLength = (
  *
  *   const relaxed: MaxLengthArray<16, string> = input; // OK (8 <= 16)
  *
- *   assert.deepStrictEqual(tags.length, 3);
+ *   assert.strictEqual(tags.length, 3);
  *
- *   assert.deepStrictEqual(relaxed.length, 3);
+ *   assert.strictEqual(relaxed.length, 3);
  * }
  *
  * // curried version
@@ -207,9 +207,9 @@ const hasMaxLength = (
  *
  *   const relaxed: BoundedLengthArray<0, 100, number> = input; // OK ([1, 5] ⊆ [0, 100])
  *
- *   assert.deepStrictEqual(selection[0], 1);
+ *   assert.strictEqual(selection[0], 1);
  *
- *   assert.deepStrictEqual(relaxed.length, 3);
+ *   assert.strictEqual(relaxed.length, 3);
  * }
  *
  * // curried version
@@ -271,7 +271,7 @@ const hasBoundedLength = (
   minLength: SupportedLength,
   maxLength: SupportedLength,
   xs: readonly unknown[],
-): boolean => xs.length >= minLength && xs.length <= maxLength;
+): boolean => minLength <= xs.length && xs.length <= maxLength;
 
 /**
  * Type guard that checks if an array has exactly `length` elements.
@@ -306,9 +306,9 @@ const hasBoundedLength = (
  *
  *   const atMost5: MaxLengthArray<5, number> = input; // OK (3 <= 5)
  *
- *   assert.deepStrictEqual(rgb[0], 255);
+ *   assert.strictEqual(rgb[0], 255);
  *
- *   assert.deepStrictEqual(atMost5.length, 3);
+ *   assert.strictEqual(atMost5.length, 3);
  * }
  *
  * // curried version