ts-fortress 1.0.0

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "ts-fortress",
+  "version": "1.0.0",
+  "private": false,
+  "keywords": [
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noshiro-pf/ts-fortress.git"
+  },
+  "license": "Apache-2.0",
+  "author": "noshiro-pf <noshiro.pf@gmail.com>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/type.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/type.d.mts",
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsx ./scripts/cmd/build.mjs",
+    "check-all": "tsx ./scripts/cmd/check-all.mjs",
+    "check:ext": "tsx ./scripts/cmd/check-ext.mjs",
+    "cspell": "cspell \"**\" --gitignore --gitignore-root ./ --no-progress",
+    "doc": "tsx ./scripts/cmd/gen-docs.mjs",
+    "fmt": "format-diff-from origin/main",
+    "fmt:full": "prettier --write .",
+    "gi": "gen-index-ts ./src --index-ext .mts --export-ext .mjs --target-ext .mts --target-ext .tsx --fmt 'npm run fmt'",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "md": "markdownlint-cli2",
+    "test": "npm run z:vitest -- run",
+    "test:cov": "npm run z:vitest -- run --coverage",
+    "test:cov:ui": "vite preview --outDir ./coverage",
+    "test:ui": "npm run z:vitest -- --ui",
+    "testw": "npm run z:vitest -- watch",
+    "tsc": "tsc --noEmit",
+    "tscw": "tsc --noEmit --watch -p ./tsconfig.json",
+    "type-check": "tsc --noEmit",
+    "update-packages": "npx npm-check-updates -u --install always",
+    "z:vitest": "vitest --config ./configs/vitest.config.ts"
+  },
+  "dependencies": {
+    "ts-data-forge": "^3.0.5",
+    "ts-type-forge": "^2.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.33.0",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-strip": "^3.0.4",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.4",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/node": "^24.2.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "cspell": "^9.2.0",
+    "eslint": "^9.33.0",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-array-func": "5.0.2",
+    "eslint-plugin-functional": "9.0.2",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-prefer-arrow-functions": "3.6.2",
+    "eslint-plugin-promise": "7.2.1",
+    "eslint-plugin-security": "3.0.1",
+    "eslint-plugin-unicorn": "60.0.0",
+    "eslint-plugin-vitest": "0.5.4",
+    "fast-glob": "^3.3.3",
+    "markdownlint-cli2": "^0.18.1",
+    "prettier": "^3.6.2",
+    "prettier-plugin-organize-imports": "^4.2.0",
+    "prettier-plugin-packagejson": "^2.5.19",
+    "rollup": "^4.46.2",
+    "semantic-release": "^24.2.7",
+    "ts-repo-utils": "^6.0.0",
+    "tslib": "^2.8.1",
+    "tsx": "^4.20.4",
+    "typedoc": "^0.28.10",
+    "typedoc-plugin-markdown": "^4.8.1",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.39.1",
+    "vitest": "^3.2.4"
+  }
+}

package/src/array/array-of-length.mts

@@ -0,0 +1,76 @@
+import { Arr, Result } from 'ts-data-forge';
+import { type Type } from '../type.mjs';
+import {
+  createAssertFn,
+  createCastFn,
+  createIsFn,
+  validationErrorMessage,
+} from '../utils/index.mjs';
+
+export const arrayOfLength = <A, N extends SmallUint>(
+  size: N,
+  elementType: Type<A>,
+  options?: Readonly<{
+    typeName?: string;
+    defaultValue?: ArrayOfLength<N, A>;
+  }>,
+): Type<ArrayOfLength<N, A>> => {
+  type T = ArrayOfLength<N, A>;
+
+  const {
+    typeName,
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    defaultValue = Arr.create(size, elementType.defaultValue) as T,
+  } = options ?? {};
+
+  const typeNameFilled: string =
+    typeName ?? `[${Arr.create(size, elementType.typeName).join(', ')}]`;
+
+  const validate: Type<T>['validate'] = (a) => {
+    if (!Arr.isArray(a)) {
+      return Result.err([
+        validationErrorMessage(a, 'The value is expected to be an array'),
+      ]);
+    }
+
+    if (a.length !== size) {
+      return Result.err([
+        `The value is expected to be an array of length ${size}, but it is ${a.length}.`,
+      ]);
+    }
+
+    for (const [index, el] of a.entries()) {
+      const res = elementType.validate(el);
+
+      if (Result.isErr(res)) {
+        const message = validationErrorMessage(
+          el,
+          `The array element is expected to be <${elementType.typeName}>`,
+          (str) => `but the actual value at index ${index} is '${str}'`,
+        );
+
+        return Result.err([message, ...res.value]);
+      }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return Result.ok(a as unknown as T);
+  };
+
+  const fill: Type<T>['fill'] = (a) =>
+    Arr.isArray(a)
+      ? // TODO: remove as
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        (Arr.map(Arr.seq(size), (i) => elementType.fill(a[i]) satisfies A) as T)
+      : defaultValue;
+
+  return {
+    typeName: typeNameFilled,
+    defaultValue,
+    fill,
+    validate,
+    is: createIsFn(validate),
+    cast: createCastFn(validate),
+    assertIs: createAssertFn(validate),
+  };
+};

package/src/array/array-of-length.test.mts

@@ -0,0 +1,113 @@
+import { expectType } from 'ts-data-forge';
+import { number } from '../primitives/index.mjs';
+import { type TypeOf } from '../type.mjs';
+import { arrayOfLength } from './array-of-length.mjs';
+
+describe('arrayOfLength', () => {
+  describe('arg patterns', () => {
+    test('without explicit default value', () => {
+      expect(arrayOfLength(3, number()).defaultValue).toStrictEqual([0, 0, 0]);
+    });
+
+    test('with explicit default value, case 1', () => {
+      expect(arrayOfLength(3, number(2)).defaultValue).toStrictEqual([2, 2, 2]);
+    });
+
+    test('with explicit default value, case 2', () => {
+      expect(
+        arrayOfLength(4, number(0), {
+          typeName: 'xs',
+          defaultValue: [1, 2, 3, 4],
+        }).defaultValue,
+      ).toStrictEqual([1, 2, 3, 4]);
+    });
+  });
+
+  const xs = arrayOfLength(4, number(0), {
+    typeName: 'xs',
+    defaultValue: [1, 2, 3, 4],
+  });
+
+  type Xs = TypeOf<typeof xs>;
+
+  expectType<Xs, ArrayOfLength<4, number>>('=');
+
+  expectType<typeof xs.defaultValue, Xs>('=');
+
+  describe('is', () => {
+    test('truthy case', () => {
+      const ys: unknown = [5, 6, 7, 8];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(true);
+    });
+
+    test('falsy case 1', () => {
+      const ys: unknown = [];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(false);
+    });
+
+    test('falsy case 2', () => {
+      const ys: unknown = ['1', '', 3];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(false);
+    });
+  });
+
+  describe('validate', () => {
+    test('falsy case 1', () => {
+      const ys: unknown = [];
+
+      expect(xs.validate(ys).value).toStrictEqual([
+        'The value is expected to be an array of length 4, but it is 0.',
+      ]);
+    });
+
+    test('falsy case 2', () => {
+      const ys: unknown = [0, '1', '', 3];
+
+      expect(xs.validate(ys).value).toStrictEqual([
+        `The array element is expected to be <number>, but the actual value at index 1 is '"1"'.`,
+        `The value is expected to be <number>, but it is actually '"1"'.`,
+      ]);
+    });
+  });
+
+  describe('fill', () => {
+    test('noop', () => {
+      const ys: unknown = [1, 2, 3];
+
+      expect(xs.fill(ys)).toStrictEqual([1, 2, 3, 0]);
+    });
+
+    test('fill with the default value', () => {
+      const ys: unknown = ['1', '', 3];
+
+      expect(xs.fill(ys)).toStrictEqual([0, 0, 3, 0]);
+    });
+
+    test('fill empty array', () => {
+      const ys: unknown = [];
+
+      expect(xs.fill(ys)).toStrictEqual([0, 0, 0, 0]);
+    });
+  });
+});

package/src/array/array.mts

@@ -0,0 +1,62 @@
+import { Arr, Result } from 'ts-data-forge';
+import { type Type } from '../type.mjs';
+import {
+  createAssertFn,
+  createCastFn,
+  createIsFn,
+  validationErrorMessage,
+} from '../utils/index.mjs';
+
+export const array = <A,>(
+  elementType: Type<A>,
+  options?: Partial<
+    Readonly<{
+      typeName: string;
+      defaultValue: readonly A[];
+    }>
+  >,
+): Type<readonly A[]> => {
+  type T = readonly A[];
+
+  const { typeName, defaultValue = [] } = options ?? {};
+
+  const typeNameFilled: string = typeName ?? `(${elementType.typeName})[]`;
+
+  const validate: Type<T>['validate'] = (a) => {
+    if (!Arr.isArray(a)) {
+      return Result.err([
+        validationErrorMessage(a, 'The value is expected to be an array'),
+      ]);
+    }
+
+    for (const [index, el] of a.entries()) {
+      const res = elementType.validate(el);
+
+      if (Result.isErr(res)) {
+        const message = validationErrorMessage(
+          el,
+          `The array element is expected to be <${elementType.typeName}>`,
+          (str) => `but the actual value at index ${index} is '${str}'`,
+        );
+
+        return Result.err([message, ...res.value]);
+      }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return Result.ok(a as T);
+  };
+
+  const fill: Type<T>['fill'] = (a) =>
+    Arr.isArray(a) ? a.map((e) => elementType.fill(e)) : defaultValue;
+
+  return {
+    typeName: typeNameFilled,
+    defaultValue,
+    fill,
+    validate,
+    is: createIsFn(validate),
+    assertIs: createAssertFn(validate),
+    cast: createCastFn(validate),
+  };
+};

package/src/array/array.test.mts

@@ -0,0 +1,84 @@
+import { expectType } from 'ts-data-forge';
+import { number } from '../primitives/index.mjs';
+import { type TypeOf } from '../type.mjs';
+import { array } from './array.mjs';
+
+describe('array', () => {
+  describe('arg patterns', () => {
+    test('without explicit default value', () => {
+      expect(array(number()).defaultValue).toStrictEqual([]);
+    });
+
+    test('with explicit default value', () => {
+      expect(
+        array(number(0), {
+          typeName: 'xs',
+          defaultValue: [],
+        }).defaultValue,
+      ).toStrictEqual([]);
+    });
+  });
+
+  const xs = array(number(0), {
+    typeName: 'xs',
+    defaultValue: [],
+  });
+
+  type Xs = TypeOf<typeof xs>;
+
+  expectType<Xs, readonly number[]>('=');
+
+  expectType<typeof xs.defaultValue, Xs>('=');
+
+  describe('is', () => {
+    test('truthy case', () => {
+      const ys: unknown = [1, 2, 3];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(true);
+    });
+
+    test('falsy case', () => {
+      const ys: unknown = ['1', '', 3];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(false);
+    });
+  });
+
+  describe('validate', () => {
+    test('falsy case', () => {
+      const ys: unknown = ['1', '', 3];
+
+      expect(xs.is(ys)).toBe(false);
+      expect(xs.validate(ys).value).toStrictEqual([
+        `The array element is expected to be <number>, but the actual value at index 0 is '"1"'.`,
+        `The value is expected to be <number>, but it is actually '"1"'.`,
+      ]);
+    });
+  });
+
+  describe('fill', () => {
+    test('noop', () => {
+      const ys: unknown = [1, 2, 3];
+
+      expect(xs.fill(ys)).toStrictEqual([1, 2, 3]);
+    });
+
+    test('fill with the default value', () => {
+      const ys: unknown = ['1', '', 3];
+
+      expect(xs.fill(ys)).toStrictEqual([0, 0, 3]);
+    });
+  });
+});

package/src/array/index.mts

@@ -0,0 +1,4 @@
+export * from './array-of-length.mjs';
+export * from './array.mjs';
+export * from './non-empty-array.mjs';
+export * from './tuple.mjs';

package/src/array/non-empty-array.mts

@@ -0,0 +1,70 @@
+import { Arr, Result } from 'ts-data-forge';
+import { type Type } from '../type.mjs';
+import {
+  createAssertFn,
+  createCastFn,
+  createIsFn,
+  validationErrorMessage,
+} from '../utils/index.mjs';
+
+export const nonEmptyArray = <A,>(
+  elementType: Type<A>,
+  options?: Readonly<{
+    typeName?: string;
+    defaultValue?: NonEmptyArray<A>;
+  }>,
+): Type<NonEmptyArray<A>> => {
+  type T = NonEmptyArray<A>;
+
+  const { typeName, defaultValue = Arr.newArray(1, elementType.defaultValue) } =
+    options ?? {};
+
+  const typeNameFilled: string =
+    typeName ?? `NonEmptyArray<${elementType.typeName}>`;
+
+  const validate: Type<T>['validate'] = (a) => {
+    if (!Arr.isArray(a)) {
+      return Result.err([
+        validationErrorMessage(a, 'The value is expected to be an array'),
+      ]);
+    }
+
+    if (Arr.isEmpty(a)) {
+      return Result.err([
+        'The value is expected to be a non-empty array, but it is empty.',
+      ]);
+    }
+
+    for (const [index, el] of a.entries()) {
+      const res = elementType.validate(el);
+
+      if (Result.isErr(res)) {
+        const message = validationErrorMessage(
+          el,
+          `The array element is expected to be <${elementType.typeName}>`,
+          (str) => `but the actual value at index ${index} is '${str}'`,
+        );
+
+        return Result.err([message, ...res.value]);
+      }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return Result.ok(a as unknown as T);
+  };
+
+  const fill: Type<T>['fill'] = (a) =>
+    Arr.isArray(a) && Arr.isNonEmpty(a)
+      ? Arr.map(a, (e) => elementType.fill(e))
+      : defaultValue;
+
+  return {
+    typeName: typeNameFilled,
+    defaultValue,
+    fill,
+    validate,
+    is: createIsFn(validate),
+    assertIs: createAssertFn(validate),
+    cast: createCastFn(validate),
+  };
+};

package/src/array/non-empty-array.test.mts

@@ -0,0 +1,113 @@
+import { expectType } from 'ts-data-forge';
+import { number } from '../primitives/index.mjs';
+import { type TypeOf } from '../type.mjs';
+import { nonEmptyArray } from './non-empty-array.mjs';
+
+describe('nonEmptyArray', () => {
+  describe('arg patterns', () => {
+    test('without explicit default value', () => {
+      expect(nonEmptyArray(number()).defaultValue).toStrictEqual([0]);
+    });
+
+    test('with explicit default value, case 1', () => {
+      expect(nonEmptyArray(number(1)).defaultValue).toStrictEqual([1]);
+    });
+
+    test('with explicit default value, case 2', () => {
+      expect(
+        nonEmptyArray(number(0), {
+          typeName: 'xs',
+          defaultValue: [2],
+        }).defaultValue,
+      ).toStrictEqual([2]);
+    });
+  });
+
+  const xs = nonEmptyArray(number(0), {
+    defaultValue: [1],
+    typeName: 'xs',
+  });
+
+  type Xs = TypeOf<typeof xs>;
+
+  expectType<Xs, NonEmptyArray<number>>('=');
+
+  expectType<typeof xs.defaultValue, Xs>('=');
+
+  describe('is', () => {
+    test('truthy case', () => {
+      const ys: unknown = [1, 2, 3];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(true);
+    });
+
+    test('falsy case 1', () => {
+      const ys: unknown = [];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(false);
+    });
+
+    test('falsy case 2', () => {
+      const ys: unknown = ['1', '', 3];
+
+      if (xs.is(ys)) {
+        expectType<typeof ys, Xs>('=');
+      } else {
+        expectType<typeof ys, unknown>('=');
+      }
+
+      expect(xs.is(ys)).toBe(false);
+    });
+  });
+
+  describe('validate', () => {
+    test('falsy case 1', () => {
+      const ys: unknown = [];
+
+      expect(xs.validate(ys).value).toStrictEqual([
+        'The value is expected to be a non-empty array, but it is empty.',
+      ]);
+    });
+
+    test('falsy case 2', () => {
+      const ys: unknown = ['1', '', 3];
+
+      expect(xs.validate(ys).value).toStrictEqual([
+        `The array element is expected to be <number>, but the actual value at index 0 is '"1"'.`,
+        `The value is expected to be <number>, but it is actually '"1"'.`,
+      ]);
+    });
+  });
+
+  describe('fill', () => {
+    test('noop', () => {
+      const ys: unknown = [1, 2, 3];
+
+      expect(xs.fill(ys)).toStrictEqual([1, 2, 3]);
+    });
+
+    test('fill with the default value', () => {
+      const ys: unknown = ['1', '', 3];
+
+      expect(xs.fill(ys)).toStrictEqual([0, 0, 3]);
+    });
+
+    test('fill empty array', () => {
+      const ys: unknown = [];
+
+      expect(xs.fill(ys)).toStrictEqual([1]);
+    });
+  });
+});

package/src/array/tuple.mts

@@ -0,0 +1,72 @@
+import { Arr, Result } from 'ts-data-forge';
+import { type Type, type TypeOf } from '../type.mjs';
+import {
+  createAssertFn,
+  createCastFn,
+  createIsFn,
+  validationErrorMessage,
+} from '../utils/index.mjs';
+
+type MapTuple<T extends readonly Type<unknown>[]> = {
+  readonly [K in keyof T]: TypeOf<T[K]>;
+};
+
+export const tuple = <const A extends readonly Type<unknown>[]>(
+  types: A,
+  options?: Partial<Readonly<{ typeName?: string }>>,
+): Type<MapTuple<A>> => {
+  type T = MapTuple<A>;
+
+  const { typeName = 'tuple' } = options ?? {};
+
+  const defaultValue = Arr.map(
+    types,
+    (t) => t.defaultValue,
+  ) satisfies MapTuple<A>;
+
+  const validate: Type<T>['validate'] = (a) => {
+    if (!Arr.isArray(a)) {
+      return Result.err([
+        validationErrorMessage(a, 'The value is expected to be an array'),
+      ]);
+    }
+
+    if (a.length !== types.length) {
+      return Result.err([
+        `The length of tuple is expected to be ${types.length}, but it is actually ${a.length}.`,
+      ]);
+    }
+
+    for (const [index, [typeDef, el]] of Arr.zip(types, a).entries()) {
+      const res = typeDef.validate(el);
+
+      if (Result.isErr(res)) {
+        const message = validationErrorMessage(
+          el,
+          `The tuple element at ${index} is expected to be <${typeDef.typeName}>`,
+        );
+
+        return Result.err([message, ...res.value]);
+      }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return Result.ok(a as T);
+  };
+
+  const fill: Type<T>['fill'] = (a) =>
+    !Arr.isArray(a)
+      ? defaultValue
+      : // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        (types.map((t, i) => t.fill(a[i])) as MapTuple<A>);
+
+  return {
+    typeName,
+    defaultValue,
+    fill,
+    validate,
+    is: createIsFn(validate),
+    assertIs: createAssertFn(validate),
+    cast: createCastFn(validate),
+  };
+};