@guillaume-docquier/tools-ts 8.6.1 → 9.1.0

package/README.md

@@ -35,6 +35,15 @@ external APIs, CLI input, local storage, or other unknown data.
 | `getEnumKey` | Looks up the enum key associated with a value.                                    | You have an enum value and need the more descriptive key for display, logs, or diagnostics. |
 | `asArray`    | Normalizes a single value or array into an array.                                 | An API accepts both `T` and `T[]`, but downstream logic should iterate uniformly.           |
 
+### Zod Parsing
+
+Use these tools when constructing a value from trusted, typed data through a Zod schema. Install Zod in the consuming project to use them.
+
+| Export         | What it is                                                                       | Use it when                                                        |
+| -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| typedParse     | Parses a typed, deeply unbranded value with a Zod schema and returns its output. | Invalid data is an internal invariant violation that should throw. |
+| safeTypedParse | The non-throwing counterpart, returning a Zod safe parse result.                 | Validation may fail and the caller will handle the result.         |
+
 ### Numeric Utilities
 
 Use these tools when code needs reusable numeric operations or validated
@@ -49,9 +58,10 @@ intervals.
 
 Use this tool when code needs shared ordering helpers.
 
-| Export | What it is                                     | Use it when                                                                             |
-| ------ | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `Sort` | Comparator helpers for common sort operations. | You want a shared sorting utility instead of rewriting compare callbacks at call sites. |
+| Export       | What it is                                                                     | Use it when                                                                             |
+| ------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `Sort`       | Direction-aware numeric and property comparators, plus comparator composition. | You want a shared sorting utility instead of rewriting compare callbacks at call sites. |
+| `Comparator` | Helper type to define comparators compatible with the Sort utilities.          | You define sorting comparators.                                                         |
 
 ### Randomness
 

package/dist/Sort.d.ts

@@ -1,18 +1,29 @@
-export declare const Sort: {
+declare enum SortDirection {
+    /**
+     * From smallest to biggest.
+     */
+    Ascending = "Ascending",
     /**
-     * Sorts numbers by ascending values
+     * From biggest to smallest.
      */
-    byAscending: (a: number, b: number) => number;
+    Descending = "Descending"
+}
+export type Comparator<T> = (first: T, second: T) => number;
+export declare const Sort: {
+    Direction: typeof SortDirection;
     /**
-     * Sorts records by a numeric property in ascending order
+     * Composes comparators.
      */
-    byAscendingProperty: <TProperty extends PropertyKey>(property: TProperty) => <TRecord extends Record<TProperty, number>>(a: TRecord, b: TRecord) => number;
+    compose: <T>(...comparators: ReadonlyArray<Comparator<T>>) => Comparator<T>;
     /**
-     * Sorts numbers by ascending values
+     * Compares numbers in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescending: (a: number, b: number) => number;
+    numeric: (direction?: SortDirection) => Comparator<number>;
     /**
-     * Sorts records by a numeric property in descending order
+     * Compares records by a numeric property in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescendingProperty: <TProperty extends PropertyKey>(property: TProperty) => <TRecord extends Record<TProperty, number>>(a: TRecord, b: TRecord) => number;
+    byNumericProperty: <TProperty extends PropertyKey>(property: TProperty, direction?: SortDirection) => <TRecord extends Record<TProperty, number>>(first: TRecord, second: TRecord) => number;
 };
+export {};

package/dist/Sort.js

@@ -1,27 +1,49 @@
-export const Sort = {
+var SortDirection;
+(function (SortDirection) {
     /**
-     * Sorts numbers by ascending values
+     * From smallest to biggest.
      */
-    byAscending: (a, b) => {
-        return a - b;
-    },
+    SortDirection["Ascending"] = "Ascending";
+    /**
+     * From biggest to smallest.
+     */
+    SortDirection["Descending"] = "Descending";
+})(SortDirection || (SortDirection = {}));
+export const Sort = {
+    Direction: SortDirection,
     /**
-     * Sorts records by a numeric property in ascending order
+     * Composes comparators.
      */
-    byAscendingProperty: (property) => (a, b) => {
-        return Sort.byAscending(a[property], b[property]);
+    compose: (...comparators) => {
+        return (first, second) => {
+            for (const comparator of comparators) {
+                const comparison = comparator(first, second);
+                if (comparison !== 0) {
+                    return comparison;
+                }
+            }
+            return 0;
+        };
     },
     /**
-     * Sorts numbers by ascending values
+     * Compares numbers in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescending: (a, b) => {
-        return b - a;
+    numeric: (direction = SortDirection.Ascending) => {
+        switch (direction) {
+            case SortDirection.Ascending:
+                return (first, second) => first - second;
+            case SortDirection.Descending:
+                return (first, second) => second - first;
+        }
     },
     /**
-     * Sorts records by a numeric property in descending order
+     * Compares records by a numeric property in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescendingProperty: (property) => (a, b) => {
-        return Sort.byDescending(a[property], b[property]);
+    byNumericProperty: (property, direction = SortDirection.Ascending) => {
+        const compare = Sort.numeric(direction);
+        return (first, second) => compare(first[property], second[property]);
     },
 };
 //# sourceMappingURL=Sort.js.map

package/dist/Sort.js.map

@@ -1 +1 @@
-{"version":3,"file":"Sort.js","sourceRoot":"","sources":["../src/Sort.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB;;OAEG;IACH,WAAW,EAAE,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;QAC5C,OAAO,CAAC,GAAG,CAAC,CAAA;IACd,CAAC;IAED;;OAEG;IACH,mBAAmB,EACjB,CAAgC,QAAmB,EAAE,EAAE,CACvD,CAA4C,CAAU,EAAE,CAAU,EAAU,EAAE;QAC5E,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;IACnD,CAAC;IAEH;;OAEG;IACH,YAAY,EAAE,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;QAC7C,OAAO,CAAC,GAAG,CAAC,CAAA;IACd,CAAC;IAED;;OAEG;IACH,oBAAoB,EAClB,CAAgC,QAAmB,EAAE,EAAE,CACvD,CAA4C,CAAU,EAAE,CAAU,EAAU,EAAE;QAC5E,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;IACpD,CAAC;CACJ,CAAA"}
+{"version":3,"file":"Sort.js","sourceRoot":"","sources":["../src/Sort.ts"],"names":[],"mappings":"AAAA,IAAK,aAUJ;AAVD,WAAK,aAAa;IAChB;;OAEG;IACH,wCAAuB,CAAA;IAEvB;;OAEG;IACH,0CAAyB,CAAA;AAC3B,CAAC,EAVI,aAAa,KAAb,aAAa,QAUjB;AAID,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,SAAS,EAAE,aAAa;IAExB;;OAEG;IACH,OAAO,EAAE,CAAI,GAAG,WAAyC,EAAiB,EAAE;QAC1E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YACvB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;gBACrC,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;gBAC5C,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;oBACrB,OAAO,UAAU,CAAA;gBACnB,CAAC;YACH,CAAC;YAED,OAAO,CAAC,CAAA;QACV,CAAC,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,OAAO,EAAE,CAAC,SAAS,GAAkB,aAAa,CAAC,SAAS,EAAsB,EAAE;QAClF,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,aAAa,CAAC,SAAS;gBAC1B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM,CAAA;YAC1C,KAAK,aAAa,CAAC,UAAU;gBAC3B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,GAAG,KAAK,CAAA;QAC5C,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,iBAAiB,EAAE,CAAgC,QAAmB,EAAE,SAAS,GAAkB,aAAa,CAAC,SAAS,EAAE,EAAE;QAC5H,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QACvC,OAAO,CAA4C,KAAc,EAAE,MAAe,EAAU,EAAE,CAC5F,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC9C,CAAC;CACF,CAAA"}

package/dist/entry.tools-ts.d.ts

@@ -13,6 +13,7 @@ export { Profile } from "./Profile.js";
 export { Range } from "./Range.js";
 export { Scalar } from "./Scalar.js";
 export { TypeGuard } from "./TypeGuard.js";
+export { typedParse, safeTypedParse } from "./typedParse.js";
 export { setTimeoutAsync } from "./setTimeoutAsync.js";
 export { noop, asyncNoop } from "./noop.js";
 export { Logger } from "./logging/Logger.js";
@@ -25,7 +26,7 @@ export type { LogContext } from "./logging/log-context/LogContext.js";
 export type { LoggerContext } from "./logging/log-context/LoggerContext.js";
 export type { LogContextProvider } from "./logging/log-context/LogContextProvider.js";
 export { debounce } from "./debounce.js";
-export { Sort } from "./Sort.js";
+export { Sort, type Comparator } from "./Sort.js";
 export { Rng, type RngState } from "./rng/Rng.js";
 export type { Generator } from "./rng/Generator.js";
 export { createGeneratorStub } from "./rng/Generator.stub.js";

package/dist/entry.tools-ts.js

@@ -12,6 +12,7 @@ export { Profile } from "./Profile.js";
 export { Range } from "./Range.js";
 export { Scalar } from "./Scalar.js";
 export { TypeGuard } from "./TypeGuard.js";
+export { typedParse, safeTypedParse } from "./typedParse.js";
 export { setTimeoutAsync } from "./setTimeoutAsync.js";
 export { noop, asyncNoop } from "./noop.js";
 export { Logger } from "./logging/Logger.js";

package/dist/entry.tools-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,GAAG,EAAiB,MAAM,cAAc,CAAA;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,OAAO,EAAW,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAY,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgB,OAAO,EAAgE,MAAM,YAAY,CAAA;AAChH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAmB,MAAM,WAAW,CAAA;AACjD,OAAO,EAAE,GAAG,EAAiB,MAAM,cAAc,CAAA;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,OAAO,EAAW,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAY,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgB,OAAO,EAAgE,MAAM,YAAY,CAAA;AAChH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/typedParse.d.ts

@@ -0,0 +1,29 @@
+import type { z } from "zod";
+import type { DeepUnbranded } from "./Brand.js";
+/**
+ * We use zod schemas on unknown inputs to parse & validate the data.
+ * However, when you have already parsed data (usually because it is trusted data) and want to validate, using schema.parse is bad because the parameter is `unknown`, so you don't get feedback from TypeScript.
+ *
+ * Use this `typedParse` method instead, which accepts as input a strongly typed but unbranded version of the data and outputs a branded version of it, after validation.
+ *
+ * This is really just a schema.parse() with type safe inputs when you only need to run the validation part of the schema.
+ *
+ * @example
+ * ```ts
+ * typedParse(IntegerSchema, 42)   // ✓
+ * typedParse(IntegerSchema, 42.5) // throws
+ * typedParse(IntegerSchema, "42") // TS error
+ * ```
+ */
+export declare function typedParse<TSchema extends z.ZodType>(schema: TSchema, value: DeepUnbranded<z.output<TSchema>>): z.output<TSchema>;
+/**
+ * The safeParse counterpart to {@link typedParse}
+ *
+ * @example
+ * ```ts
+ * safeTypedParse(IntegerSchema, 42)   // ✓
+ * safeTypedParse(IntegerSchema, 42.5) // returns success = false
+ * safeTypedParse(IntegerSchema, "42") // TS error
+ * ```
+ */
+export declare function safeTypedParse<TSchema extends z.ZodType>(schema: TSchema, value: DeepUnbranded<z.output<TSchema>>): z.ZodSafeParseResult<z.output<TSchema>>;

package/dist/typedParse.js

@@ -0,0 +1,32 @@
+/**
+ * We use zod schemas on unknown inputs to parse & validate the data.
+ * However, when you have already parsed data (usually because it is trusted data) and want to validate, using schema.parse is bad because the parameter is `unknown`, so you don't get feedback from TypeScript.
+ *
+ * Use this `typedParse` method instead, which accepts as input a strongly typed but unbranded version of the data and outputs a branded version of it, after validation.
+ *
+ * This is really just a schema.parse() with type safe inputs when you only need to run the validation part of the schema.
+ *
+ * @example
+ * ```ts
+ * typedParse(IntegerSchema, 42)   // ✓
+ * typedParse(IntegerSchema, 42.5) // throws
+ * typedParse(IntegerSchema, "42") // TS error
+ * ```
+ */
+export function typedParse(schema, value) {
+    return schema.parse(value);
+}
+/**
+ * The safeParse counterpart to {@link typedParse}
+ *
+ * @example
+ * ```ts
+ * safeTypedParse(IntegerSchema, 42)   // ✓
+ * safeTypedParse(IntegerSchema, 42.5) // returns success = false
+ * safeTypedParse(IntegerSchema, "42") // TS error
+ * ```
+ */
+export function safeTypedParse(schema, value) {
+    return schema.safeParse(value);
+}
+//# sourceMappingURL=typedParse.js.map

package/dist/typedParse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedParse.js","sourceRoot":"","sources":["../src/typedParse.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU,CAA4B,MAAe,EAAE,KAAuC;IAC5G,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAe,EACf,KAAuC;IAEvC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaume-docquier/tools-ts",
-  "version": "8.6.1",
+  "version": "9.1.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",
@@ -47,7 +47,16 @@
     "semantic-release": "^25.0.9",
     "typescript": "~7.0.2",
     "vite": "^8.3.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.0",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "zod": "^4.6.5"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   },
   "lint-staged": {
     "*.{md,json,yml,yaml,css,scss}": "oxfmt --no-error-on-unmatched-pattern",