@guillaume-docquier/tools-ts 9.0.0 → 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

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";

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,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"}
+{"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": "9.0.0",
+  "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",