@ptolemy2002/ts-utils 2.5.0 → 3.0.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:
 
@@ -58,13 +63,16 @@ The condition can then be passed to the `valueConditionMatches` function along w
 ### OptionalValueCondition<T>
 This type is the same as `ValueCondition<T>` except that the value can also be `null`, indicating any value is acceptable.
 
-### AdvancedConditionConstructorArgs<T>
+### AdvancedCondition<T>
 ```typescript
-type AdvancedConditionConstructorArgs<T> = {
-    include?: T | ((v: T) => boolean) | (T | ((v: T) => boolean) | false)[],
-    exclude?: T | ((v: T) => boolean) | (T | ((v: T) => boolean | false))[],
+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))[],
     match?: (a: T, b: T) => boolean
-};
+}, [typeof advancedConditionSymbol]>;
 ```
 
 ### ValuesIntersection<T>
@@ -73,54 +81,31 @@ This type returns an intersection of all the possible values in an object of typ
 ### 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`.
+## Functions
+The following functions are available in the library:
 
-### WithBrand<T, B>
-Using the `Contains` type, this type returns `T` if it is branded with `B` and `never` otherwise.
+### isAdvancedCondition
+#### Description
+This function takes a value of any type and returns a boolean indicating whether the value is an instance of `AdvancedCondition` by checking for the `__isAdvancedCondition` property and ensuring it is `true`.
 
-## Values
-### declare const __brand
-A unique symbol used to define type brands.
+#### Parameters
+- `value` (`any`) - The value to check.
 
-## Classes
-The following classes are available in the library:
+#### Returns
+`value is AdvancedCondition<any>` - Boolean determining whether the value is an instance of `AdvancedCondition`. It functions as a type guard in Typescript.
 
-### AdvancedCondition<T>
+### createAdvancedCondition<T>
 #### Description
-This class is used to create an advanced condition for matching a subset of type `T`. Note that a normal object with the same properties as `AdvancedConditionConstructorArgs<T>` cannot be used in place of this class instance, contrary to how Typescript normally handles classes. A hack has been used to disable this behavior.
+This function creates an instance of `AdvancedCondition` with the specified arguments and sensible defaults applied.
 
-#### Properties
-- `args: AdvancedConditionConstructorArgs<T>` - The arguments used to construct the condition.
-    - `include?` (`AdvancedConditionConstructorArgs["include"]`) - The value or values that must be included in the condition. If this is a function, it will be used to determine if a value should be included. If this is an instance of `Condition`, it will be used as a subcondition. If this is `false`, it will be ignored.
-    - `exclude?` (`AdvancedConditionConstructorArgs["exclude"]`) - The value or values that must be excluded from the condition. If this is a function, it will be used to determine if a value should be excluded. If this is an instance of `Condition`, it will be used as a subcondition. If this is `false`, it will be ignored.
-    - `match?` (`AdvancedConditionConstructorArgs["match"]`) - The function used to determine if two values are equal. If this is not specified, it will default to `Object.is`.
+#### Parameters
+- `condition` (`WithoutBrand<Omit<AdvancedCondition<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 a function, it will be used to determine if a value should be included. If this is `false`, it will be ignored.
+    - `exclude` - The value or values that must be excluded from the condition. If this is a function, it will be used to determine if a value should be excluded. If this is `false`, it will be ignored.
+    - `match` - The function used to determine if two values are equal. If this is not specified, it will default to `Object.is`.
 
-## Functions
-The following functions are available in the library:
+#### Returns
+`AdvancedCondition<T>` - The advanced condition instance.
 
 ### valueConditionMatches<T>
 #### Description
@@ -131,7 +116,7 @@ This function takes a value of type `T` and a condition of type `OptionalValueCo
 - `condition` (`OptionalValueCondition<T>`) - The condition to check against the value.
 
 #### Returns
-- `boolean` - Whether the value meets the condition.
+`boolean` - Whether the value meets the condition.
 
 ### omit<T, K extends keyof T>
 #### Description
@@ -142,10 +127,11 @@ This function takes an object of type `T` and a list of keys `K` and returns a n
 - `keys` (`K[]`) - The keys to omit from the object.
 
 #### Returns
-- `Omit<T, K>` - The object with the keys omitted.
+`Omit<T, K>` - The object with the keys omitted.
 
 ## 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[] = []> = {
@@ -24,19 +25,15 @@ export type AtLeastOne<T, U = {
     [K in keyof T]: Pick<T, K>;
 }> = Partial<T> & U[keyof U];
 export type Override<T, U> = Omit<T, keyof U> & U;
-export type AdvancedConditionConstructorArgs<T> = {
+export declare const advancedConditionSymbol: unique symbol;
+export 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))[];
     match?: (a: T, b: T) => boolean;
-};
-export declare class AdvancedCondition<T> {
-    private kind;
-    include: AdvancedConditionConstructorArgs<T>["include"];
-    exclude: AdvancedConditionConstructorArgs<T>["exclude"];
-    match?: AdvancedConditionConstructorArgs<T>["match"];
-    constructor({ include, exclude, match }?: AdvancedConditionConstructorArgs<T>);
-    static isCondition<T>(value: any): value is AdvancedCondition<T>;
-}
+}, [typeof advancedConditionSymbol]>;
+export declare function isAdvancedCondition(value: any): value is AdvancedCondition<any>;
+export declare function createAdvancedCondition<T>(condition: WithoutBrand<Omit<AdvancedCondition<T>, "__isAdvancedCondition">>): AdvancedCondition<T>;
 export type ValueCondition<T> = AdvancedCondition<T> | T | ((v: T) => boolean) | (ValueCondition<T> | false)[];
 export type OptionalValueCondition<T> = ValueCondition<T> | null;
 export declare function valueConditionMatches<T>(value: T, condition: OptionalValueCondition<T>): boolean;
@@ -47,11 +44,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 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

@@ -1,21 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AdvancedCondition = void 0;
+exports.isAdvancedCondition = isAdvancedCondition;
+exports.createAdvancedCondition = createAdvancedCondition;
 exports.valueConditionMatches = valueConditionMatches;
-exports.brandValue = brandValue;
 exports.omit = omit;
 const isCallable = require("is-callable");
-class AdvancedCondition {
-    constructor({ include = [], exclude = [], match = Object.is } = {}) {
-        this.include = include;
-        this.exclude = exclude;
-        this.match = match;
-    }
-    static isCondition(value) {
-        return value instanceof AdvancedCondition;
-    }
+const ts_brand_utils_1 = require("@ptolemy2002/ts-brand-utils");
+function isAdvancedCondition(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__isAdvancedCondition" in value && value.__isAdvancedCondition === true);
+}
+function createAdvancedCondition(condition) {
+    return {
+        __isAdvancedCondition: true,
+        include: [],
+        exclude: [],
+        match: Object.is,
+        ...(0, ts_brand_utils_1.brand)(condition)
+    };
 }
-exports.AdvancedCondition = AdvancedCondition;
 function valueConditionMatches(value, condition) {
     if (condition === null)
         return true;
@@ -24,7 +28,7 @@ function valueConditionMatches(value, condition) {
     if (isCallable(condition))
         return condition(value);
     // If the condition value here is not a condition object, it must be of type T, so we can directly compare it
-    if (!AdvancedCondition.isCondition(condition))
+    if (!isAdvancedCondition(condition))
         return Object.is(value, condition);
     let { include = [], exclude = [], match = Object.is } = condition;
     if (!Array.isArray(include))
@@ -42,9 +46,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.5.0",
+    "version": "3.0.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"
     }
 }