@ptolemy2002/ts-utils 2.2.0 → 2.4.0

package/README.md

@@ -24,6 +24,9 @@ Given a type `T`, this type loops through every key `K` and wraps that key's val
 ### MaybePromise<T>
 This type returns a union of the type `T` and a promise that resolves to the type `T`.
 
+### MaybeArray<T>
+This type returns a union of the type `T` and an array of that type.
+
 ### TAndOthers<T, K extends keyof any = PropertyKey>
 This type returns an object with all the properties of `T` and any number of other properties under keys that fit the type `K`. The additional properties will all have the type `any` because I couldn't figure out how to make them have a type that does not include `ValueOf<T>` due to the way Typescript handles mapped object types.
 
@@ -33,6 +36,12 @@ 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.
 
+### 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.
+
+### Override<T, U>
+This type returns a type that is the same as `T` except that the keys in `U` are overridden with the values in `U`.
+
 ### Rename<T, K extends keyof T, N extends string>
 This type returns a type that is the same as `T` except that the key `K` is renamed to `N`.
 
@@ -61,6 +70,42 @@ type AdvancedConditionConstructorArgs<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.
+
+## Values
+### declare const __brand
+A unique symbol used to define type brands.
+
 ## Classes
 The following classes are available in the library:
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type MaybeTransformerRecord<T, Args extends any[] = []> = {
     [K in keyof T]: MaybeTransformer<T[K], Args>;
 };
 export type MaybePromise<T> = T | Promise<T>;
+export type MaybeArray<T> = T | T[];
 export type TAndOthers<T, K extends keyof any = PropertyKey> = Record<K, any> & T;
 export type KeysMatching<T, V> = {
     [K in keyof T]-?: T[K] extends V ? K : never;
@@ -22,6 +23,7 @@ export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 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> = {
     include?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean) | false)[];
     exclude?: T | false | ((v: T) => boolean) | (T | false | ((v: T) => boolean | false))[];
@@ -44,3 +46,11 @@ export type Rename<T, K extends keyof T, N extends string> = Pick<T, Exclude<key
 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>;

package/dist/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdvancedCondition = void 0;
 exports.valueConditionMatches = valueConditionMatches;
+exports.brandValue = brandValue;
 const isCallable = require("is-callable");
 class AdvancedCondition {
     constructor({ include = [], exclude = [], match = Object.is } = {}) {
@@ -40,3 +41,6 @@ function valueConditionMatches(value, condition) {
         return !excluded(value);
     return included(value) && !excluded(value);
 }
+function brandValue(value) {
+    return value;
+}

package/package.json

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