@ptolemy2002/ts-utils 3.0.0 → 3.2.0

package/README.md

@@ -60,9 +60,19 @@ This type allows the user to specify a condition for matching a subset of type `
 
 The condition can then be passed to the `valueConditionMatches` function along with a value of type `T` to determine if the condition is met for that value.
 
+### SerializableValueCondition<T>
+This type is the same as `ValueCondition<T>` except that any function values are disallowed, making it safe for JSON serialization, assuming that `T` is also JSON-serializable.
+
+This is assignable to any field that accepts a `ValueCondition<T>`.
+
 ### OptionalValueCondition<T>
 This type is the same as `ValueCondition<T>` except that the value can also be `null`, indicating any value is acceptable.
 
+### OptionalSerializableValueCondition<T>
+This type is the same as `SerializableValueCondition<T>` except that the value can also be `null`, indicating any value is acceptable.
+
+This is assignable to any field that accepts an `OptionalValueCondition<T>`.
+
 ### AdvancedCondition<T>
 ```typescript
 declare const advancedConditionSymbol: unique symbol;
@@ -75,6 +85,21 @@ type AdvancedCondition<T> = Branded<{
 }, [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 is assignable to any field that accepts an `AdvancedCondition<T>`.
+
+### ValueConditionType
+This type is a union of string literals representing the possible types a `ValueCondition<T>` can be. It may also be a list of those same string literals plus `"false"`, representing the types of each element in an array condition. This array may be nested to any depth. To be precise, it is defined as follows:
+
+```typescript
+type ValueConditionType = "advanced" | "function" | "value" | (ValueConditionType | "false")[];
+```
+
+### SerializableValueConditionType
+This type is the same as `ValueConditionType` except that the `"function"` type is omitted, since functions are not allowed in `SerializableValueCondition<T>`.
+
 ### ValuesIntersection<T>
 This type returns an intersection of all the possible values in an object of type `T`.
 
@@ -107,6 +132,15 @@ This function creates an instance of `AdvancedCondition` with the specified argu
 #### Returns
 `AdvancedCondition<T>` - The advanced condition instance.
 
+### createSerializableAdvancedCondition<T>
+#### Description
+This function is the same as `createAdvancedCondition` except that it takes a `SerializableAdvancedCondition<T>` as its argument. The underlying object created is the same, except that the `match` function is not included.
+
+#### Parameters
+- `condition` (`WithoutBrand<Omit<SerializableAdvancedCondition<T>, "__isAdvancedCondition">>`) - The arguments to use in constructing the condition.
+    - `include` - The value or values that must be included in the condition. If this is `false`, it will be ignored.
+    - `exclude` - The value or values that must be excluded from the condition. If this is `false`, it will be ignored.
+
 ### valueConditionMatches<T>
 #### Description
 This function takes a value of type `T` and a condition of type `OptionalValueCondition<T>` and returns a boolean indicating whether the value meets the condition. If the condition is `null`, the function will always return `true`. Any instance of the value `false` will be filtered out of lists. If `match` is not specified, it will default to `Object.is`. If `include` is not specified or empty, it will be ignored and `exclude` will act as the only constraint. If `exclude` is not specified, it will be assumed to be empty.
@@ -118,6 +152,30 @@ This function takes a value of type `T` and a condition of type `OptionalValueCo
 #### Returns
 `boolean` - Whether the value meets the condition.
 
+### valueConditionType<T>
+#### Description
+This function takes a condition of type `ValueCondition<T>` and returns a string indicating the type of condition it is. The possible return values are:
+- `"advanced"` - The condition is an instance of `AdvancedCondition<T>`.
+- `"function"` - The condition is a function that takes a value of type `T` and (presumably) returns a boolean. The return type is not checked, due to potential side effects of calling the function.
+- `"value"` - The condition is a value of type `T`.
+- `(ValueConditionType | "false")[]` - The condition is an array of conditions, and the return value is an array of the types of each condition in the array.
+
+#### Parameters
+- `condition` (`ValueCondition<T>`) - The condition to check.
+
+#### Returns
+`ValueConditionType` - The type of the condition.
+
+### serializeValueConditionType<T>
+#### Description
+The same as `valueConditionType`, except that it specifically takes a `SerializableValueCondition<T>` and returns a `SerializableValueConditionType`. The difference is that function conditions are not serializable, so they are not included in the return type and cannot be specified in the argument.
+
+#### Parameters
+- `condition` (`SerializableValueCondition<T>`) - The condition to check.
+
+#### Returns
+`SerializableValueConditionType` - The type of the condition.
+
 ### omit<T, K extends keyof T>
 #### Description
 This function takes an object of type `T` and a list of keys `K` and returns a new object with all the keys in `K` removed.

package/dist/index.d.ts

@@ -32,11 +32,22 @@ export type AdvancedCondition<T> = Branded<{
     exclude?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean | false))[];
     match?: (a: T, b: T) => boolean;
 }, [typeof advancedConditionSymbol]>;
+export type SerializableAdvancedCondition<T> = Override<Omit<AdvancedCondition<T>, "match">, {
+    include?: Exclude<AdvancedCondition<T>["include"], () => any>;
+    exclude?: Exclude<AdvancedCondition<T>["exclude"], () => any>;
+}>;
 export declare function isAdvancedCondition(value: any): value is AdvancedCondition<any>;
 export declare function createAdvancedCondition<T>(condition: WithoutBrand<Omit<AdvancedCondition<T>, "__isAdvancedCondition">>): AdvancedCondition<T>;
+export declare function createSerializableAdvancedCondition<T>(condition: WithoutBrand<Omit<SerializableAdvancedCondition<T>, "__isAdvancedCondition">>): SerializableAdvancedCondition<T>;
 export type ValueCondition<T> = AdvancedCondition<T> | T | ((v: T) => boolean) | (ValueCondition<T> | false)[];
 export type OptionalValueCondition<T> = ValueCondition<T> | null;
+export type SerializableValueCondition<T> = SerializableAdvancedCondition<T> | T | (SerializableValueCondition<T> | false)[];
+export type OptionalSerializableValueCondition<T> = SerializableValueCondition<T> | null;
 export declare function valueConditionMatches<T>(value: T, condition: OptionalValueCondition<T>): boolean;
+export type ValueConditionType = "advanced" | "function" | "value" | (ValueConditionType | "false")[];
+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 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

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAdvancedCondition = isAdvancedCondition;
 exports.createAdvancedCondition = createAdvancedCondition;
+exports.createSerializableAdvancedCondition = createSerializableAdvancedCondition;
 exports.valueConditionMatches = valueConditionMatches;
+exports.valueConditionType = valueConditionType;
+exports.serializableValueConditionType = serializableValueConditionType;
 exports.omit = omit;
 const isCallable = require("is-callable");
 const ts_brand_utils_1 = require("@ptolemy2002/ts-brand-utils");
@@ -20,6 +23,14 @@ function createAdvancedCondition(condition) {
         ...(0, ts_brand_utils_1.brand)(condition)
     };
 }
+function createSerializableAdvancedCondition(condition) {
+    return {
+        __isAdvancedCondition: true,
+        include: [],
+        exclude: [],
+        ...(0, ts_brand_utils_1.brand)(condition)
+    };
+}
 function valueConditionMatches(value, condition) {
     if (condition === null)
         return true;
@@ -46,6 +57,24 @@ function valueConditionMatches(value, condition) {
         return !excluded(value);
     return included(value) && !excluded(value);
 }
+function valueConditionType(condition) {
+    // Type assertion here because TS cannot infer that the filter will remove all false values
+    if (Array.isArray(condition))
+        return condition.map(c => c === false ? "false" : valueConditionType(c));
+    if (isAdvancedCondition(condition))
+        return "advanced";
+    if (isCallable(condition))
+        return "function";
+    return "value";
+}
+function serializableValueConditionType(condition) {
+    // Type assertion here because TS cannot infer that the filter will remove all false values
+    if (Array.isArray(condition))
+        return condition.map(c => c === false ? "false" : serializableValueConditionType(c));
+    if (isAdvancedCondition(condition))
+        return "advanced";
+    return "value";
+}
 function omit(obj, ...keys) {
     const _ = { ...obj };
     keys.forEach((key) => delete _[key]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/ts-utils",
-    "version": "3.0.0",
+    "version": "3.2.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",