@guillaume-docquier/tools-ts 9.0.0 → 10.0.0

package/README.md

@@ -35,6 +35,17 @@ 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
+
+Import these tools from `@guillaume-docquier/tools-ts/schemas`. Install Zod in the consuming project to use this optional subpath; the root entry point does not load Zod.
+
+| 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.         |
+| IntegerSchema and `Integer`               | Parses and brands whole numbers.                                                 | A value must be an integer, including zero or a negative integer.  |
+| PositiveNumberSchema and `PositiveNumber` | Parses and brands numbers greater than zero.                                     | A value must be positive but may be fractional.                    |
+
 ### Numeric Utilities
 
 Use these tools when code needs reusable numeric operations or validated

package/dist/entry.schemas.d.ts

@@ -0,0 +1,3 @@
+export { IntegerSchema, type Integer } from "./schemas/Integer.js";
+export { PositiveNumberSchema, type PositiveNumber } from "./schemas/PositiveNumber.js";
+export { typedParse, safeTypedParse } from "./schemas/typedParse.js";

package/dist/entry.schemas.js

@@ -0,0 +1,4 @@
+export { IntegerSchema } from "./schemas/Integer.js";
+export { PositiveNumberSchema } from "./schemas/PositiveNumber.js";
+export { typedParse, safeTypedParse } from "./schemas/typedParse.js";
+//# sourceMappingURL=entry.schemas.js.map

package/dist/entry.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.schemas.js","sourceRoot":"","sources":["../src/entry.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,6BAA6B,CAAA;AACvF,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/schemas/Integer.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { type Branded } from "../Brand.js";
+/**
+ * A whole number, including zero and negative numbers.
+ */
+export type Integer = Branded<"Integer", number>;
+/**
+ * Parses a number as an integer.
+ */
+export declare const IntegerSchema: z.ZodPipe<z.ZodInt, z.ZodTransform<Integer, number>>;

package/dist/schemas/Integer.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { branded } from "../Brand.js";
+/**
+ * Parses a number as an integer.
+ */
+export const IntegerSchema = z.int().transform(branded);
+//# sourceMappingURL=Integer.js.map

package/dist/schemas/Integer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Integer.js","sourceRoot":"","sources":["../../src/schemas/Integer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAgB,MAAM,aAAa,CAAA;AAOnD;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAgB,CAAC,CAAA"}

package/dist/schemas/PositiveNumber.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { type Branded } from "../Brand.js";
+/**
+ * A number greater than zero; zero is neither positive nor negative.
+ */
+export type PositiveNumber = Branded<"PositiveNumber", number>;
+/**
+ * Parses a number greater than zero, including positive fractions.
+ */
+export declare const PositiveNumberSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<PositiveNumber, number>>;

package/dist/schemas/PositiveNumber.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { branded } from "../Brand.js";
+/**
+ * Parses a number greater than zero, including positive fractions.
+ */
+export const PositiveNumberSchema = z
+    .number()
+    .positive()
+    .transform(branded);
+//# sourceMappingURL=PositiveNumber.js.map

package/dist/schemas/PositiveNumber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PositiveNumber.js","sourceRoot":"","sources":["../../src/schemas/PositiveNumber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAgB,MAAM,aAAa,CAAA;AAOnD;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,SAAS,CAAC,OAAuB,CAAC,CAAA"}

package/dist/schemas/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/schemas/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/schemas/typedParse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedParse.js","sourceRoot":"","sources":["../../src/schemas/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": "10.0.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",
@@ -18,6 +18,11 @@
       "types": "./dist/entry.tools-ts.d.ts",
       "import": "./dist/entry.tools-ts.js",
       "require": "./dist/entry.tools-ts.js"
+    },
+    "./schemas": {
+      "types": "./dist/entry.schemas.d.ts",
+      "import": "./dist/entry.schemas.js",
+      "require": "./dist/entry.schemas.js"
     }
   },
   "publishConfig": {
@@ -47,7 +52,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",