@ptolemy2002/ts-utils 3.5.1 → 4.0.0

package/README.md

@@ -41,6 +41,9 @@ This type returns a union of all the keys in `T` that have a value assignable to
 ### PartialBy<T, K extends keyof T>
 This type returns a type that is the same as `T` except that the keys in `K` are optional.
 
+### RequiredBy<T, K extends keyof T>
+This type returns a type that is the same as `T` except that the keys in `K` are required.
+
 ### AtLeastOne<T, U = {[K in keyof T]: Pick<T, K> }>
 This type returns a type that is the same as `T` except that at least one key is required.
 
@@ -79,14 +82,14 @@ declare const advancedConditionSymbol: unique symbol;
 
 type AdvancedCondition<T> = Branded<{
     __isAdvancedCondition: true,
-    include?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean) | false)[],
-    exclude?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean | false))[],
+    include?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean))[],
+    exclude?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean))[],
     match?: (a: T, b: T) => boolean
 }, [typeof advancedConditionSymbol]>;
 ```
 
 ### SerializableAdvancedCondition<T>
-This type is the same as `AdvancedCondition<T>` except that the `include` and `exclude` fields cannot be functions and the `match` field is omit, making it safe for JSON serialization, assuming that `T` is also JSON-serializable. Thus, you lose the ability to use custom matching logic when using this type.
+This type is the same as `AdvancedCondition<T>` except that the `include` and `exclude` fields cannot be functions and the `match` field is omitted, making it safe for JSON serialization, assuming that `T` is also JSON-serializable. Thus, you lose the ability to use custom matching logic when using this type.
 
 This is assignable to any field that accepts an `AdvancedCondition<T>`.
 
@@ -190,25 +193,62 @@ The same as `valueConditionType`, except that it specifically takes a `Serializa
 #### Returns
 `SerializableValueConditionType` - The type of the condition.
 
-### zodSerializableAdvancedConditionSchemaTemplate<ZT extends ZodType>
+### zodAdvancedConditionSchemaTemplate<T>
+#### Description
+Given a Zod schema for `T`, this function returns a Zod schema that validates an `AdvancedCondition<T>`. The parsed output is created with `createAdvancedCondition`, so the `__isAdvancedCondition` tag and the usual defaults are always present.
+
+Input rules:
+- The input must be an object with at least one of `include`, `exclude`, or `match` defined.
+- `__isAdvancedCondition` may be provided, but only as `true`. It is not required, as the schema adds it.
+- Unknown keys are rejected. This prevents arbitrary objects from being interpreted as an empty condition that matches everything.
+
+Functions in `include`, `exclude`, and `match` are checked using `zodFunctionSchema` from `@ptolemy2002/zod-utils`. This has the following consequences:
+- The functions are **called during parsing** with the sample values. Avoid passing functions with side effects.
+- An `include` or `exclude` predicate must return a boolean when called with `sample1`.
+- A `match` function must return `true` for `(sample1, sample1)` and `false` for `(sample1, sample2)`. Choose samples that no reasonable match function would consider equal.
+- The functions in the output are wrappers that validate their arguments and return value on every call, throwing a `ZodError` if either is invalid.
+
+#### Parameters
+- `zt` (`ZodType<T>`) - The Zod schema representing the type `T`.
+- `sample1` (`T`) - A sample value used to test functions during parsing.
+- `sample2` (`T`) - A second sample value, different from `sample1`, used to test `match` functions.
+
+#### Returns
+`ZodType<AdvancedCondition<T>>` - A Zod schema that can be used to validate an `AdvancedCondition<T>`.
+
+### zodSerializableAdvancedConditionSchemaTemplate<T>
+#### Description
+The same as `zodAdvancedConditionSchemaTemplate`, except that it validates a `SerializableAdvancedCondition<T>`. The parsed output is created with `createSerializableAdvancedCondition`. The input must have at least one of `include` or `exclude` defined. Functions are not allowed anywhere, and a `match` key is rejected like any other unknown key. Because no functions are ever called, no sample values are needed.
+
+#### Parameters
+- `zt` (`ZodType<T>`) - The Zod schema representing the type `T`.
+
+#### Returns
+`ZodType<SerializableAdvancedCondition<T>>` - A Zod schema that can be used to validate a `SerializableAdvancedCondition<T>`.
+
+### zodValueConditionSchemaTemplate<T>
 #### Description
-A function that allows you to pass in a Zod schema and wrap it such that it can be used to validate a `SerializableAdvancedCondition<T>` where `T` is the type represented by the Zod schema. Note: not the full extent of recursion in `SerializableAdvancedCondition<T>` is supported, nor are functions.
+Given a Zod schema for `T`, this function returns a Zod schema that validates a `ValueCondition<T>`, including arrays nested to any depth. Advanced conditions are validated with `zodAdvancedConditionSchemaTemplate`, so the same input rules apply to them. Function conditions are called once with `sample1` during parsing, must return a boolean, and are wrapped in the same way.
+
+Options are tried in the same order `valueConditionMatches` checks them: array, function, advanced condition, then a plain value of type `T`. As a result, an object with at least one of `include`, `exclude`, or `match` and no other keys is always treated as an advanced condition, even if it would also be a valid `T`.
 
 #### Parameters
-- `zt` (`ZT`) - The Zod schema representing the type `T`.
+- `zt` (`ZodType<T>`) - The Zod schema representing the type `T`.
+- `sample1` (`T`) - A sample value used to test functions during parsing.
+- `sample2` (`T`) - A second sample value, different from `sample1`, used to test `match` functions.
 
 #### Returns
-`ZodObject<...>` - A Zod schema that can be used to validate a `SerializableAdvancedCondition<T>`.
+`ZodType<ValueCondition<T>>` - A Zod schema that can be used to validate a `ValueCondition<T>`.
 
-### zodSerializableValueConditionSchemaTemplate<ZT extends ZodType>
+### zodSerializableValueConditionSchemaTemplate<T>
 #### Description
-A function that allows you to pass in a Zod schema and wrap it such that it can be used to validate a `SerializableValueCondition<T>` where `T` is the type represented by the Zod schema. Note: not the full extent of recursion in `SerializableValueCondition<T>` is supported, nor are functions.
+The same as `zodValueConditionSchemaTemplate`, except that it validates a `SerializableValueCondition<T>`. Function conditions are not allowed, and advanced conditions are validated with `zodSerializableAdvancedConditionSchemaTemplate`. Arrays may be nested to any depth.
 
 #### Parameters
-- `zt` (`ZT`) - The Zod schema representing the type `T`.
+- `zt` (`ZodType<T>`) - The Zod schema representing the type `T`.
 
 #### Returns
-`ZodUnion<...>` - A Zod schema that can be used to validate a `SerializableValueCondition<T>`.
+`ZodType<SerializableValueCondition<T>>` - A Zod schema that can be used to validate a `SerializableValueCondition<T>`.
 
 ### omit<T, K extends keyof T>
 #### Description
@@ -230,7 +270,7 @@ An abstract class representing an object that can be treated as an array, but wi
 ## Peer Dependencies
 - `is-callable^1.2.7`
 - `@ptolemy2002/ts-brand-utils^1.0.0`
-- `@ptolemy2002/regex-utils^4.2.0`
+- `@ptolemy2002/zod-utils^1.7.0`
 - `zod^4.3.6`
 
 ## Commands

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Branded, WithoutBrand } from "@ptolemy2002/ts-brand-utils";
-import z, { ZodType } from "zod";
+import { ZodType } from "zod";
 export type ValueOf<T> = T[keyof T];
 export type MaybeTransformer<T, Args extends any[] = []> = T | ((...args: Args) => T);
 export type MaybeTransformerRecord<T, Args extends any[] = []> = {
@@ -22,6 +22,7 @@ export type KeysNotMatchingEqualTypes<T, V> = {
     [K in keyof T]-?: EqualTypes<T[K], V, never, K>;
 }[keyof T];
 export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 export type AtLeastOne<T, U = {
     [K in keyof T]: Pick<T, K>;
 }> = Partial<T> & U[keyof U];
@@ -50,26 +51,10 @@ export type ValueConditionType = "advanced" | "function" | "value" | (ValueCondi
 export type SerializableValueConditionType = "advanced" | "value" | (SerializableValueConditionType | "false")[];
 export declare function valueConditionType<T>(condition: ValueCondition<T>): ValueConditionType;
 export declare function serializableValueConditionType<T>(condition: SerializableValueCondition<T>): SerializableValueConditionType;
-export declare function zodSerializableAdvancedConditionSchemaTemplate<ZT extends ZodType>(zt: ZT): z.ZodPipe<z.ZodObject<{
-    include: z.ZodOptional<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>]>>]>>;
-    exclude: z.ZodOptional<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>]>>]>>;
-}, z.core.$strip>, z.ZodTransform<SerializableAdvancedCondition<z.core.$InferUnionOutput<ZT>>, {
-    include?: false | z.core.$InferUnionOutput<ZT> | (false | z.core.$InferUnionOutput<ZT>)[];
-    exclude?: false | z.core.$InferUnionOutput<ZT> | (false | z.core.$InferUnionOutput<ZT>)[];
-}>>;
-export declare function zodSerializableValueConditionSchemaTemplate<ZT extends ZodType>(zt: ZT): z.ZodUnion<readonly [ZT, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodPipe<z.ZodObject<{
-    include: z.ZodOptional<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>]>>]>>;
-    exclude: z.ZodOptional<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>]>>]>>;
-}, z.core.$strip>, z.ZodTransform<SerializableAdvancedCondition<z.core.$InferUnionOutput<ZT>>, {
-    include?: false | z.core.$InferUnionOutput<ZT> | (false | z.core.$InferUnionOutput<ZT>)[];
-    exclude?: false | z.core.$InferUnionOutput<ZT> | (false | z.core.$InferUnionOutput<ZT>)[];
-}>>]>>, z.ZodPipe<z.ZodObject<{
-    include: z.ZodOptional<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>]>>]>>;
-    exclude: z.ZodOptional<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>, z.ZodArray<z.ZodUnion<readonly [ZT, z.ZodLiteral<false>]>>]>>;
-}, z.core.$strip>, z.ZodTransform<SerializableAdvancedCondition<z.core.$InferUnionOutput<ZT>>, {
-    include?: false | z.core.$InferUnionOutput<ZT> | (false | z.core.$InferUnionOutput<ZT>)[];
-    exclude?: false | z.core.$InferUnionOutput<ZT> | (false | z.core.$InferUnionOutput<ZT>)[];
-}>>]>;
+export declare function zodAdvancedConditionSchemaTemplate<T>(zt: ZodType<T>, sample1: T, sample2: T): ZodType<AdvancedCondition<T>>;
+export declare function zodSerializableAdvancedConditionSchemaTemplate<T>(zt: ZodType<T>): ZodType<SerializableAdvancedCondition<T>>;
+export declare function zodValueConditionSchemaTemplate<T>(zt: ZodType<T>, sample1: T, sample2: T): ZodType<ValueCondition<T>>;
+export declare function zodSerializableValueConditionSchemaTemplate<T>(zt: ZodType<T>): ZodType<SerializableValueCondition<T>>;
 export type Rename<T, K extends keyof T, N extends string> = Pick<T, Exclude<keyof T, K>> & {
     [P in N]: T[K];
 };

package/dist/index.js

@@ -10,12 +10,14 @@ exports.createSerializableAdvancedCondition = createSerializableAdvancedConditio
 exports.valueConditionMatches = valueConditionMatches;
 exports.valueConditionType = valueConditionType;
 exports.serializableValueConditionType = serializableValueConditionType;
+exports.zodAdvancedConditionSchemaTemplate = zodAdvancedConditionSchemaTemplate;
 exports.zodSerializableAdvancedConditionSchemaTemplate = zodSerializableAdvancedConditionSchemaTemplate;
+exports.zodValueConditionSchemaTemplate = zodValueConditionSchemaTemplate;
 exports.zodSerializableValueConditionSchemaTemplate = zodSerializableValueConditionSchemaTemplate;
 exports.omit = omit;
 const is_callable_1 = __importDefault(require("is-callable"));
 const ts_brand_utils_1 = require("@ptolemy2002/ts-brand-utils");
-const regex_utils_1 = require("@ptolemy2002/regex-utils");
+const zod_utils_1 = require("@ptolemy2002/zod-utils");
 const zod_1 = __importDefault(require("zod"));
 function isAdvancedCondition(value) {
     return (typeof value === "object" &&
@@ -83,29 +85,94 @@ function serializableValueConditionType(condition) {
         return "advanced";
     return "value";
 }
-const zodValueConditionGenericFactory = (0, regex_utils_1.zodGenericFactory)();
+function zodAdvancedConditionSchemaTemplate(zt, sample1, sample2) {
+    const validatorFunctionSchema = (0, zod_utils_1.zodFunctionSchema)({
+        input: zod_1.default.tuple([zt]),
+        output: zod_1.default.boolean(),
+        trials: [
+            {
+                input: [sample1],
+                outputSchema: zod_1.default.boolean(),
+                error: "forbid"
+            }
+        ]
+    });
+    // Options are ordered to mirror the checks in valueConditionMatches,
+    // since z.union returns the first option that succeeds.
+    const validatorItemSchema = zod_1.default.union([zod_1.default.literal(false), validatorFunctionSchema, zt]);
+    const validatorUnionSchema = zod_1.default.union([zod_1.default.array(validatorItemSchema), validatorItemSchema]);
+    // Strict and requiring at least one key so that arbitrary objects are not interpreted
+    // as an empty (match-all) condition.
+    // The tag is accepted but not required, as the transform always injects it.
+    return zod_1.default.strictObject({
+        __isAdvancedCondition: zod_1.default.literal(true).optional(),
+        include: validatorUnionSchema.optional(),
+        exclude: validatorUnionSchema.optional(),
+        match: (0, zod_utils_1.zodFunctionSchema)({
+            input: zod_1.default.tuple([zt, zt]),
+            output: zod_1.default.boolean(),
+            trials: [
+                {
+                    id: "matches_same_object",
+                    input: [sample1, sample1],
+                    outputSchema: zod_1.default.literal(true),
+                    error: "forbid"
+                },
+                // Requires sample1 and sample2 to be values that no reasonable
+                // match function would consider equal
+                {
+                    id: "does_not_match_different_objects",
+                    input: [sample1, sample2],
+                    outputSchema: zod_1.default.literal(false),
+                    error: "forbid"
+                }
+            ]
+        }).optional()
+    }).refine((data) => data.include !== undefined || data.exclude !== undefined || data.match !== undefined, { message: "At least one of include, exclude, or match must be specified" }).transform(({ __isAdvancedCondition, ...data }) => createAdvancedCondition(data));
+}
 function zodSerializableAdvancedConditionSchemaTemplate(zt) {
-    return zod_1.default.object({
-        include: zod_1.default.union([
-            zt,
-            zod_1.default.literal(false),
-            zod_1.default.array(zod_1.default.union([zt, zod_1.default.literal(false)]))
-        ]),
-        exclude: zod_1.default.union([
-            zt,
-            zod_1.default.literal(false),
-            zod_1.default.array(zod_1.default.union([zt, zod_1.default.literal(false)]))
-        ])
-    }).partial().transform((data) => createSerializableAdvancedCondition(data));
+    const valueItemSchema = zod_1.default.union([zod_1.default.literal(false), zt]);
+    const valueUnionSchema = zod_1.default.union([zod_1.default.array(valueItemSchema), valueItemSchema]);
+    // Strict, so a "match" key (or any other unknown key) is rejected
+    return zod_1.default.strictObject({
+        __isAdvancedCondition: zod_1.default.literal(true).optional(),
+        include: valueUnionSchema.optional(),
+        exclude: valueUnionSchema.optional()
+    }).refine((data) => data.include !== undefined || data.exclude !== undefined, { message: "At least one of include or exclude must be specified" }).transform(({ __isAdvancedCondition, ...data }) => createSerializableAdvancedCondition(data));
+}
+function zodValueConditionSchemaTemplate(zt, sample1, sample2) {
+    // Options are ordered to mirror the checks in valueConditionMatches,
+    // since z.union returns the first option that succeeds.
+    const schema = zod_1.default.union([
+        zod_1.default.array(zod_1.default.union([zod_1.default.literal(false),
+            // This lazy evaluation is what allows recursion
+            zod_1.default.lazy(() => schema)])),
+        (0, zod_utils_1.zodFunctionSchema)({
+            input: zod_1.default.tuple([zt]),
+            output: zod_1.default.boolean(),
+            trials: [
+                {
+                    input: [sample1],
+                    outputSchema: zod_1.default.boolean()
+                }
+            ]
+        }),
+        zodAdvancedConditionSchemaTemplate(zt, sample1, sample2),
+        zt
+    ]);
+    return schema;
 }
 function zodSerializableValueConditionSchemaTemplate(zt) {
-    return zodValueConditionGenericFactory(zt)((s) => {
-        return zod_1.default.union([
-            s,
-            zod_1.default.array(zod_1.default.union([s, zod_1.default.literal(false), zodSerializableAdvancedConditionSchemaTemplate(s)])),
-            zodSerializableAdvancedConditionSchemaTemplate(s)
-        ]);
-    });
+    // Essentially same as above, but with no function option and deferring to the serializable advanced condition schema template
+    // instead of the regular advanced condition schema template
+    const schema = zod_1.default.union([
+        zod_1.default.array(zod_1.default.union([zod_1.default.literal(false),
+            // This lazy evaluation is what allows recursion
+            zod_1.default.lazy(() => schema)])),
+        zodSerializableAdvancedConditionSchemaTemplate(zt),
+        zt
+    ]);
+    return schema;
 }
 function omit(obj, ...keys) {
     const _ = { ...obj };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/ts-utils",
-    "version": "3.5.1",
+    "version": "4.0.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -27,14 +27,14 @@
         "release-major": "bash ./scripts/release.sh major"
     },
     "peerDependencies": {
-        "@ptolemy2002/regex-utils": "^4.2.0",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
+        "@ptolemy2002/zod-utils": "^1.7.0",
         "is-callable": "^1.2.7",
         "zod": "^4.3.6"
     },
     "devDependencies": {
-        "@ptolemy2002/regex-utils": "^4.2.0",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
+        "@ptolemy2002/zod-utils": "^1.7.0",
         "@types/is-callable": "~1.1.2",
         "is-callable": "^1.2.7",
         "zod": "^4.3.6"