@ptolemy2002/ts-utils 2.6.0 → 3.1.0

package/README.md

@@ -9,6 +9,11 @@ import { functionName } from '@ptolemy2002/ts-utils';
 const { functionName } = require('@ptolemy2002/ts-utils');
 ```
 
+## Type Reference
+```typescript
+import { Branded, WithoutBrand } from "@ptolemy2002/ts-brand-utils";
+```
+
 ## Types
 The following types are available in the library:
 
@@ -55,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;
@@ -70,48 +85,17 @@ 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>`.
+
 ### ValuesIntersection<T>
 This type returns an intersection of all the possible values in an object of type `T`.
 
 ### Contains<L extends unknown[], T>
 This type returns a boolean indicating whether the type `T` is contained in the array `L`.
 
-### BrandTag<B extends unknown[]>
-This type returns a record with a single key of type `__brand` and a value of type `B`. It represents a brand that can be used to differentiate between types.
-
-Branded types are useful for making checks at runtime through assertion functions and recognizing these checks at compile time. For example:
-```typescript
-function isPositive(value: number): value is Branded<number, ["positive"]> {
-    return value > 0;
-}
-
-function takesPositive(value: WithBrand<number, "positive">) {
-    // Do something with the positive value
-}
-
-const value: number = 5;
-if (isPositive(value)) {
-    // Succeeds because value has been asserted to be positive
-    takesPositive(value);
-}
-
-// Error: value may not be positive, as we cannot guarantee the assertion succeeded
-takesPositive(value);
-```
-
-### Branded<T, B extends unknown[]>
-This type returns a type that is the same as `T` except that it is branded with the type `B`.
-
-### WithBrand<T, B>
-Using the `Contains` type, this type returns `T` if it is branded with `B` and `never` otherwise.
-
-### WithoutBrand<T extends BrandTag<unknown[]>>
-This type returns the inner type without the brand applied to it.
-
-## Values
-### declare const __brand
-A unique symbol used to define type brands.
-
 ## Functions
 The following functions are available in the library:
 
@@ -138,6 +122,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.
@@ -162,6 +155,7 @@ This function takes an object of type `T` and a list of keys `K` and returns a n
 
 ## Peer Dependencies
 - `is-callable^1.2.7`
+- `@ptolemy2002/ts-brand-utils^1.0.0`
 
 ## Commands
 The following commands exist in the project:

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Branded, WithoutBrand } from "@ptolemy2002/ts-brand-utils";
 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[] = []> = {
@@ -31,10 +32,17 @@ 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 Rename<T, K extends keyof T, N extends string> = Pick<T, Exclude<keyof T, K>> & {
     [P in N]: T[K];
@@ -43,12 +51,4 @@ export type ValuesIntersection<T> = ValueOf<{
     [K in keyof T]: (x: T[K]) => void;
 }> extends (x: infer I) => void ? I : never;
 export type Contains<L extends unknown[], T> = L extends [...unknown[], T] ? true : L extends [T, ...unknown[]] ? true : L extends [T] ? true : false;
-export declare const __brand: unique symbol;
-export type BrandTag<B extends unknown[]> = {
-    readonly [__brand]: B;
-};
-export type Branded<T, B extends unknown[]> = T & BrandTag<B>;
-export type WithBrand<T, B> = T extends BrandTag<unknown[]> ? (Contains<T[typeof __brand], B> extends true ? T : never) : never;
-export type WithoutBrand<T extends BrandTag<unknown[]>> = Omit<T, typeof __brand>;
-export declare function brandValue<B extends unknown[], T>(value: T): Branded<T, B>;
 export declare function omit<T extends object, K extends keyof T>(obj: T, ...keys: K[]): Omit<T, K>;

package/dist/index.js

@@ -2,12 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAdvancedCondition = isAdvancedCondition;
 exports.createAdvancedCondition = createAdvancedCondition;
+exports.createSerializableAdvancedCondition = createSerializableAdvancedCondition;
 exports.valueConditionMatches = valueConditionMatches;
-exports.brandValue = brandValue;
 exports.omit = omit;
 const isCallable = require("is-callable");
+const ts_brand_utils_1 = require("@ptolemy2002/ts-brand-utils");
 function isAdvancedCondition(value) {
-    return "__isAdvancedCondition" in value && value.__isAdvancedCondition === true;
+    return (typeof value === "object" &&
+        value !== null &&
+        "__isAdvancedCondition" in value && value.__isAdvancedCondition === true);
 }
 function createAdvancedCondition(condition) {
     return {
@@ -15,7 +18,15 @@ function createAdvancedCondition(condition) {
         include: [],
         exclude: [],
         match: Object.is,
-        ...brandValue(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) {
@@ -44,9 +55,6 @@ function valueConditionMatches(value, condition) {
         return !excluded(value);
     return included(value) && !excluded(value);
 }
-function brandValue(value) {
-    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": "2.6.0",
+    "version": "3.1.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -27,10 +27,12 @@
         "release-major": "bash ./scripts/release.sh major"
     },
     "peerDependencies": {
-        "is-callable": "^1.2.7"
+        "is-callable": "^1.2.7",
+        "@ptolemy2002/ts-brand-utils": "^1.0.0"
     },
     "devDependencies": {
         "@types/is-callable": "~1.1.2",
+        "@ptolemy2002/ts-brand-utils": "^1.0.0",
         "is-callable": "^1.2.7"
     }
 }