@strapi/types 5.0.0-beta.0 → 5.0.0-beta.2

package/dist/utils/index.d.ts

@@ -0,0 +1,180 @@
+export * as Constants from './constants';
+export * as Array from './array';
+export * as Guard from './guard';
+export * as Object from './object';
+export * as String from './string';
+export * as Function from './function';
+export * as Tuple from './tuple';
+export * from './expression';
+export * from './json';
+/**
+ * `Get<TValue, TKey>` obtains the type of a specific property (key-value pair) within an object or type.
+ *
+ * @template TValue The initial object type from which a property's type should be extracted.
+ * @template TKey A specific key, existing within `TValue`.
+ *
+ * @example
+ * // Utilizing Get to extract types from an object
+ * type ExampleObject = { foo: 'bar', 'bar': 'foo' };
+ *
+ * // Extract `foo`'s type from the object. This infers and outputs the type 'bar'.
+ * type FooType = Get<ExampleObject, 'foo'>;
+ * let fooVar: FooType = 'bar'; // This is valid
+ *
+ * // Similar extraction for `bar`
+ * type BarType = Get<ExampleObject, 'bar'>;
+ * let barVar: BarType = 'foo'; // This is valid
+ */
+export type Get<TValue, TKey extends keyof TValue> = TValue[TKey];
+/**
+ * `Flatten intersection types.
+ *
+ * It acts upon each constituent type within the provided intersection, and extracts its properties
+ * to form a new, unified object type where properties do not retain their original type-specific
+ * distinctions.
+ *
+ * It’s useful when there's a need to treat an intersection type as a single unified object type,
+ * while ensuring that the properties of each component type in the intersection are accounted for.
+ *
+ * @template T The type parameter indicating the intersection type that is to be simplified. This must extend `unknown`.
+ *
+ * @example
+ * Consider the following example with two distinct types `A` and `B`:
+ * ```typescript
+ * type A = { a: number };
+ * type B = { b: string };
+ * ```
+ * If we were to create an intersection of these two types as `C`:
+ * ```typescript
+ * type C = A & B;
+ * ```
+ * The usual operations on `C` would account for the distinct types `A` and `B`. However, when we want to treat it as a single unified object type, we can apply `Simplify` in the following way:
+ * ```typescript
+ * type D = Simplify<C>;
+ * ```
+ * Now, `D` is a single object type with properties from both `A` and `B`, and we can operate on it as:
+ * ```typescript
+ * let obj: D = { a: 5, b: 'hello' };
+ * ```
+ *
+ * @remark
+ * While this type is beneficial in certain contexts where treating intersection types as single unified objects is desirable (e.g. when exposing
+ * complex types to end-users), it's important to remember that it strips the original type information from the properties.
+ *
+ * Thus, it may not be suitable in situations where retaining the distinction between types present in the intersection is important.
+ */
+export type Simplify<T> = {
+    [TKey in keyof T]: T[TKey];
+};
+/**
+ * Utility type that creates a new type by excluding properties from the left type ({@link TLeft}) that exist in the right type ({@link TRight}).
+ *
+ * @template TLeft
+ * @template TRight
+ *
+ * @example
+ * type User = {
+ *   id: number,
+ *   name: string,
+ *   email: string,
+ * };
+ *
+ * type Credentials = {
+ *   email: string,
+ *   password: string,
+ * };
+ *
+ * type UserWithoutCredentials = Without<User, Credentials>;
+ *
+ * const user: UserWithoutCredentials = {
+ *     id: 1,
+ *     name: 'Alice'
+ *     // no email property because it's excluded by the Without type
+ * };
+ */
+export type Without<TLeft, TRight> = {
+    [key in Exclude<keyof TLeft, keyof TRight>]?: never;
+};
+/**
+ * Creates a type that is mutually exclusive between two given types.
+ *
+ * @template TLeft - The first type.
+ * @template TRight - The second type.
+ *
+ * @remarks
+ * This type is used to create a type that can be either TLeft or TRight, but not both at the same time.
+ *
+ * @example
+ * // Example 1: XOR type with two object types
+ * type A = { a: number };
+ * type B = { b: string };
+ *
+ * const value1: XOR<A, B> = { a: 1 }; // Valid, TLeft type A is assigned
+ * const value2: XOR<A, B> = { b: "hello" }; // Valid, TRight type B is assigned
+ * const value3: XOR<A, B> = { a: 1, b: "hello" }; // Invalid, both types A and B cannot be assigned at the same time
+ *
+ * // Example 2: XOR type with object type and string type
+ * type C = XOR<A, string>;
+ *
+ * const value4: C = { a: 1 }; // Valid, object type A is assigned
+ * const value5: C = "hello"; // Valid, string type is assigned
+ * const value6: C = { a: 1, b: "hello" }; // Invalid, both object type A and string type cannot be assigned at the same time
+ */
+export type XOR<TLeft, TRight> = TLeft | TRight extends object ? (Without<TLeft, TRight> & TRight) | (Without<TRight, TLeft> & TLeft) : TLeft | TRight;
+/**
+ * The `Cast` type is designed for casting a value of type {@link TValue} into type {@link TType}, thus making sure {@link TValue} extends {@link TType}.
+ *
+ * If the casting is impossible ({@link TValue} does not extend {@link TType}), it returns `never`.
+ *
+ * @template TValue - The type to cast.
+ * @template TType - The target type.
+ *
+ * @example
+ * // In this example, the String 'Hello' is attempted to be cast to a number,
+ * // which is not possible. Thus, the result would be 'never'.
+ * type ImpossibleCasting = Cast<'Hello', number>; // this will be 'never'
+ *
+ * @example
+ * // In this example, the String 'Hello' is attempted to be cast to a String,
+ * // which is possible. Thus, the result would be 'Hello'.
+ * type PossibleCasting = Cast<'Hello', string>; // this will be 'Hello'
+ *
+ */
+export type Cast<TValue, TType> = TValue extends TType ? TValue : never;
+/**
+ * The `PartialWithThis<T>` type extends the functionality of two types: {@link Partial} and {@link ThisType}.
+ *
+ * It creates a type that represents an object with a subset of properties from the provided
+ * type {@link T} merged with a pseudo `this` context for methods, based on the same type parameter.
+ *
+ * - {@link Partial} makes all properties of the given type optional.
+ * - {@link ThisType} defines what `this` refers to within a method of the final object.
+ *
+ * @template T The type to create a subset from and to use for the pseudo 'this' context.
+ *
+ * It can be any TypeScript type such as interface, class, primitive, or even another
+ * generic type.
+ *
+ * @example
+ * ```typescript
+ * interface MyObject {
+ *     property1: string;
+ *     property2: number;
+ *     method(): void;
+ * }
+ *
+ * let foo: PartialWithThis<MyObject> = {
+ *     property1: 'Hello',
+ *     method() {
+ *       // Here, `this` refers to `MyObject`
+ *       console.log(this.property1);
+ *     },
+ *     // `property2` is optional
+ * };
+ * ```
+ *
+ * @remark
+ * This type can be useful when working with partial data and object methods that contain a pseudo `this` context.
+ */
+export type PartialWithThis<T> = Partial<T> & ThisType<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AAEvB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,IAAI,SAAS,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI;KAAG,GAAG,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK;CAAE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,GAAG,MAAM,SAAS,MAAM,GAC1D,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,GACpE,KAAK,GAAG,MAAM,CAAC;AAEnB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,SAAS,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC"}

package/dist/utils/json.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The `JSONValue` type embodies all potential JSON data forms ({@link JSONPrimitive}, {@link JSONObject}, and {@link JSONArray}).
+ *
+ * @note `JSONValue` does not introduce any new type parameters; it merely aggregates {@link JSONPrimitive}, {@link JSONObject}, and {@link JSONArray}.
+ *
+ * @example
+ * ```typescript
+ * function processJSON(jsonData: JSONValue): void {
+ *   if (Array.isArray(jsonData)) {
+ *     console.log('This is a JSONArray: ', JSON.stringify(jsonData, null, 2));
+ *   } else if (typeof jsonData === 'object') {
+ *     console.log('This is a JSONObject: ', JSON.stringify(jsonData, null, 2));
+ *   } else {
+ *     console.log('This is a JSONPrimitive: ', jsonData);
+ *   }
+ * }
+ *
+ * processJSON(['hello', { anotherKey: 'anotherValue' }]);
+ * // This is a JSONArray: ["hello", { "anotherKey": "anotherValue" }]
+ *
+ * processJSON({ key: 'value' });
+ * // This is a JSONObject: { "key": "value" }
+ *
+ * processJSON(10);
+ * // This is a JSONPrimitive: 10
+ * ```
+ *
+ * @see {@link JSONPrimitive} - The simplest form of `JSONValue`, corresponds to basic JSON data types.
+ * @see {@link JSONObject} - A potential `JSONValue`, encapsulates JSON object structures.
+ * @see {@link JSONArray} - A potential `JSONValue`, encapsulates JSON arrays.
+ */
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
+/**
+ * The `JSONPrimitive` type models the fundamental data types (`string`, `number`, `boolean`, `null`) of JSON in TypeScript.
+ *
+ * @example
+ * ```typescript
+ * declare function set(key: string, value: JSONPrimitive): void;
+ *
+ * set('string', 'foo'); // This is valid
+ * set('number', 42); // This is valid
+ * set('boolean', true); // This is valid
+ * set('null', null); // This is valid
+ * set('array', []); // Error
+ * set('undefined', undefined); // Error
+ * ```
+ *
+ * @see {@link JSONValue} - The potential forms of JSON data, including `JSONPrimitive`.
+ * @see {@link JSONObject} - Incorporated in {@link JSONValue}, represents JSON objects.
+ * @see {@link JSONArray} - Incorporated in {@link JSONValue}, represents JSON arrays.
+ *
+ * @remarks
+ * `JSONPrimitive` provides a foundation for describing JSON data.
+ * Combined with {@link JSONObject} and {@link JSONArray}, they encompass all possible JSON data types.
+ */
+export type JSONPrimitive = string | number | boolean | null;
+/**
+ * The `JSONArray` type models a standard JSON array in TypeScript, which allows manipulation of arrays of {@link JSONValue} elements.
+ *
+ * @example
+ * ```typescript
+ * // Create a JSONArray consisting of different JSONValues
+ * let jsonArray: JSONArray = ['hello', 10, true, null, {key: 'value'}, ['nested array']];
+ *
+ * function prettyPrint(jsonArray: JSONArray): void {
+ *  jsonArray.forEach(item => {
+ *    if(typeof item === 'object' && item !== null) {
+ *      // If it's a JSONObject or another JSONArray, stringify it
+ *      console.log(JSON.stringify(item, null, 2));
+ *    } else {
+ *      // If it's a JSONPrimitive, print it directly
+ *      console.log(item);
+ *    }
+ *  });
+ * }
+ *
+ * prettyPrint(jsonArray); // Will print all items in a friendly format to the console
+ * ```
+ *
+ * This type is part of a series of types used for modeling all possible JSON values in TypeScript.
+ * @see {@link JSONValue} - The supertype of all elements that a `JSONArray` can contain.
+ * @see {@link JSONPrimitive} - The simplest kind of `JSONValue` that a `JSONArray` can contain.
+ * @see {@link JSONObject} - A possible `JSONValue` that a `JSONArray` can contain.
+ *
+ * @remarks
+ * The `JSONArray` is a versatile type that can contain various kinds of JSON data, even nested arrays or objects.
+ */
+export type JSONArray = Array<JSONValue>;
+/**
+ * The `JSONObject` interface formally defines a JavaScript object with string keys and values of type {@link JSONValue}.
+ *
+ * It models standard JSON objects as TypeScript types, facilitating their manipulation.
+ *
+ * @example
+ * ```typescript
+ * function addToJSONObject(key: string, value: JSONValue, jsonObject: JSONObject): JSONObject {
+ *   // Copy the existing JSONObject
+ *   let updatedObject: JSONObject = { ...jsonObject };
+ *
+ *   // Add the new key-value pair
+ *   updatedObject[key] = value;
+ *
+ *   // Return the updated JSONObject
+ *   return updatedObject;
+ * }
+ * ```
+ *
+ * @see {@link JSONValue} - The permitted types for values within the `JSONObject` (primitives, objects, or arrays).
+ * @see {@link JSONPrimitive} - The basis for JSON data, used in {@link JSONValue}.
+ * @see {@link JSONArray} - Arrays used in {@link JSONValue}.
+ *
+ * @remarks
+ * The keys of the `JSONObject` are always of type string, as per the standard JSON specification.
+ * Values may take any valid {@link JSONValue}, allowing nested data structures.
+ */
+export interface JSONObject {
+    [key: string]: JSONValue;
+}
+//# sourceMappingURL=json.d.ts.map

package/dist/utils/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B"}

package/dist/utils/object.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Extracts object's (`TValue`) keys where the key's value type extends the given `TTest` type.
+ *
+ * @template TValue - The original object type.
+ * @template TTest - The test type. Keys of TValue having values that extend this type are extracted.
+ * @template TExtract - An optional constraint for the keys of TValue.
+ *
+ * @example
+ *
+ *   // Here TValue is `{ foo: 'bar', bar: 'foo', foobar: 2 }` and TTest is `string`.
+ *   // So it extracts keys `foo` and `bar`, because their values are string type.
+ *   type keys = KeysBy<{ foo: 'bar', bar: 'foo', foobar: 2 }, string> // 'foo' | 'bar'
+ *
+ * @example
+ *
+ *   // Here TValue is `{ foo: { x: 'foo' }, bar: { x: 'bar' }, other: { x: '42' } }` and TTest is `{ x: 'foo' | 'bar' }`.
+ *   // So it extracts keys `foo` and `bar`, because their values are extending `{ x: 'foo' | 'bar' }`.
+ *   type Base = { x: 'foo' | 'bar' };
+ *   type Obj = { foo: { x: 'foo' }, bar: { x: 'bar' }, other: { x: '42' } };
+ *   type X = KeysBy<Obj, Base> // 'foo' | 'bar'
+ *
+ * @see {@link KeysExcept}
+ * @see {@link PickBy}
+ */
+export type KeysBy<TValue, TTest, TExtract extends keyof any = keyof any> = {
+    [key in keyof TValue & TExtract]: TValue[key] extends TTest ? key : never;
+}[keyof TValue & TExtract];
+/**
+ * Extracts the keys of a given object ({@link TValue}). It includes only those keys which do not map to a value of type {@link TTest}`.
+ *
+ * @template TValue - The object whose keys are to be examined and selectively retrieved
+ * @template TTest - The type of value to be used as an exclusion criterion for selecting keys from `TValue`
+ * @template TExtract - An optional union of keys to constrain the keys that are being examined. If not provided, it defaults to examining all keys in `TValue`.
+ *
+ * @example
+ * ```typescript
+ * // In this example, KeysExcept is used to fetch keys from the object which do not have string type values
+ * type ExampleType = { foo: 'bar', bar: 'foo', foobar: 2 }
+ * type ResultType = KeysExcept<ExampleType, string>
+ * // The resulting type is "foobar"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In this example, we use a base type to define allowed value types and only fetch those keys from the object that have values not extending the base type
+ * type Base = { x: 'foo' | 'bar' };
+ * type Obj = { foo: { x: 'foo' }, bar: { x: 'bar' }, other: { x: '42' } };
+ * type X = KeysBy<Obj, Base>
+ * // The resulting type is "other"
+ * ```
+ */
+export type KeysExcept<TValue, TTest, TExtract extends keyof any = keyof any> = {
+    [key in keyof TValue & TExtract]: TValue[key] extends TTest ? never : key;
+}[keyof TValue & TExtract];
+/**
+ * Select properties from an object ({@link TValue}), only if their types extend a specific test type ({@link TTest}).
+ *
+ * @template TValue - The object type from which properties are selected.
+ * @template TTest - The test type. Properties of TValue extending this type are selected.
+ *
+ * @example
+ *
+ *  // If we have this:
+ *  type FruitAttributes = { color: string, taste: string, weight: number, isOrganic: boolean };
+ *
+ *  // And we use `PickBy` like so:
+ *  type StringAttributes = PickBy<FruitAttributes, string>;
+ *
+ *  // Then, `StringAttributes` will equal: `{ color: string, taste: string }`
+ */
+export type PickBy<TValue, TTest> = Pick<TValue, KeysBy<TValue, TTest>>;
+/**
+ * Creates a new type from a given type ({@link TValue}), and select specific
+ * keys ({@link TKeys}) to be optionally present in the new type.
+ *
+ * @template TValue The original type of object.
+ * @template TKeys A union of selected {@link TValue} object keys that should be partial/optional in the new type.
+ *
+ * @example
+ * ```typescript
+ * type Person = {
+ *   name: string;
+ *   age: number;
+ * };
+ *
+ * type PartialAgePerson = PartialBy<Person, 'age'>;
+ *
+ * // the type PartialAgePerson is now equivalent to:
+ * // {
+ * //   name: string;
+ * //   age?: number;
+ * // }
+ * ```
+ */
+export type PartialBy<TValue, TKeys extends keyof TValue> = Omit<TValue, TKeys> & Partial<Pick<TValue, TKeys>>;
+/**
+ * Extracts all unique values from a given object as a union type.
+ *
+ * @template TObject - An object from which values are to be extracted. It must extend the `object` type.
+ *
+ * @remark
+ * It works with non-primitive values as well. Hence, if a value is an object, it is included as is. Primitive types are included directly.
+ *
+ * @example
+ * With a simple object:
+ * ```TypeScript
+ * type SimpleExample = Values<{
+ *     a: 'one',
+ *     b: 'two',
+ *     c: 3
+ * }>;
+ * // Result: 'one' | 'two' | 3
+ * ```
+ *
+ * @example
+ * With complex (non-primitive) values in an object:
+ * ```TypeScript
+ * type ComplexExample = Values<{
+ *     a: { x: 10 },
+ *     b: { y: 'twenty' },
+ *     c: { z: true }
+ * }>;
+ * // Result: { x: 10 } | { y: 'twenty' } | { z: true }
+ * ```
+ */
+export type Values<TObject extends object> = TObject[keyof TObject];
+/**
+ * Provides a way to set deeply-nested properties within `TObject` to optional.
+ *
+ * @template TObject Type of the object that will become deeply partial.
+ *
+ * @example
+ * ```typescript
+ * interface Person {
+ *   name: string;
+ *   age: number;
+ *   address: {
+ *     city: string;
+ *     street: string;
+ *     postalCode: number;
+ *   };
+ * }
+ *
+ * const partialPerson: DeepPartial<Person> = {}; // This is now valid
+ *
+ * // You can assign partially filled objects
+ * const anotherPerson: DeepPartial<Person> = {
+ *   name: 'John',
+ *   address: {
+ *     city: 'San Francisco',
+ *     // street and postal code are optional
+ *   }
+ * }
+ * ```
+ */
+export type DeepPartial<TObject> = TObject extends object ? {
+    [TKey in keyof TObject]?: DeepPartial<TObject[TKey]>;
+} : TObject;
+/**
+ * Creates a new type by replacing properties of {@link TObject} with properties from {@link TNew}.
+ *
+ * This is particularly useful to fine-tune the shape of an object type by altering some of its properties while keeping the rest intact.
+ *
+ * @template TObject - A type that extends `object`. This should be the original type that you intend to transform.
+ * @template TNew - A partial type of {@link TObject} where keys are replaced with new types.
+ *
+ * @example
+ *
+ * ```typescript
+ * type Original = { foo: number, bar: number}; // Declare original type
+ * type Transformation = { foo: string }; // Declare keys to replace from original type
+ *
+ * type Result = Replace<Original, Transformation>;
+ * // The transformed type now becomes { foo: string, bar: number }
+ * ```
+ */
+export type Replace<TObject extends object, TNew extends Partial<{
+    [key in keyof TObject]: unknown;
+}>> = Omit<TObject, keyof TNew> & TNew;
+//# sourceMappingURL=object.d.ts.map

package/dist/utils/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,SAAS,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI;KACzE,GAAG,IAAI,MAAM,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,GAAG,GAAG,KAAK;CAC1E,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,SAAS,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI;KAC7E,GAAG,IAAI,MAAM,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,KAAK,GAAG,GAAG;CAC1E,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC;AAE3B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,SAAS,MAAM,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,GAC7E,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,CAAC,MAAM,OAAO,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,OAAO,SAAS,MAAM,GACrD;KACG,IAAI,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD,GACD,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,OAAO,CACjB,OAAO,SAAS,MAAM,EACtB,IAAI,SAAS,OAAO,CAAC;KAAG,GAAG,IAAI,MAAM,OAAO,GAAG,OAAO;CAAE,CAAC,IACvD,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC"}

package/dist/utils/string.d.ts

@@ -0,0 +1,154 @@
+import type { Extends } from './expression';
+/**
+ * Alias for any literal type (useful for template string parameters)
+ *
+ * @see {@link Split}
+ * @see {@link Suffix}
+ * @see {@link Prefix}
+ * @see {@link StartsWith}
+ * @see {@link EndsWith}
+ */
+export type Literal = string | number | bigint | boolean;
+/**
+ * Ensures that a string is not empty.
+ *
+ * @template T - The type that extends a string.
+ *
+ * @example
+ * // T is assigned a string type
+ * type A = NonEmpty<string>;
+ * // A can be any string except the empty string
+ * let a: A = "hello"; // Valid
+ * a = ""; // Error: Type '""' is not assignable to type 'NonEmpty<string>'
+ *
+ * @example
+ * // T is assigned a string literal type
+ * type B = NonEmpty<"hello">;
+ * // B can only be "hello"
+ * let b: B = "hello"; // Valid
+ * b = ""; // Error: Type '""' is not assignable to type 'NonEmpty<"hello">'
+ */
+export type NonEmpty<T extends string> = T extends '' ? never : T;
+/**
+ * Splits a given string ({@link TValue}) around occurrences of a given separator ({@link TSeparator}).
+ *
+ * The resulting type is an array where each item is a part of the original string that falls between two instances of the separator.
+ *
+ * If the string does not contain the separator, the array will contain just the original string.
+ *
+ * If the string is empty, the result is an empty array.
+ *
+ * @template TValue - The string to split. Must extend `string`.
+ * @template TSeparator - The character(s) used to determine in which locations the string should be split. Must be a `string`.
+ *
+ * @example
+ *
+ * ```typescript
+ *  type Example = Split<'a.b.c.d', '.'>;  // Output will be: ['a', 'b', 'c', 'd']
+ * ```
+ * In the above example, the string 'a.b.c.d' is split around occurrences of the '.' separator.
+ *
+ * @example
+ *
+ * ```typescript
+ *  type ExampleUnion = Split<'a.b-c', '.' | '-'>;  // Output will be: ['a', 'b-c'] | ['a.b', 'c']
+ * ```
+ * The split operation will distribute the union members and create two possible return type for the union
+ */
+export type Split<TValue extends string, TSeparator extends string> = {
+    [TSep in TSeparator]: TValue extends `${infer TLeft}${TSep}${infer TRight}` ? [TLeft, ...Split<TRight, TSep>] : TValue extends '' ? [] : [TValue];
+}[TSeparator];
+/**
+ * The `Suffix` type appends a literal suffix ({@link TSuffix}) to the end of a provided string ({@link TValue}).
+ *
+ * @template TValue - The string to add the suffix to.
+ * @template TSuffix - It extends the {@link Literal} type, and represents the suffix to append.
+ *
+ * @example
+ * ```typescript
+ * // A type that appends '.com' to a string
+ * type DomainName = Suffix<string, '.com'>;
+ * const myComDomain: DomainName = 'example.com'; // This is valid
+ * const myNetDomain: DomainName = 'example.net'; // This is not valid
+ *
+ * // A variant using `number` as literal
+ * type SuffixedNumber = Suffix<string, 1>;
+ * const mySuffixedNumber: SuffixedNumber = 'example1'; // Also valid
+ * ```
+ */
+export type Suffix<TValue extends string, TSuffix extends Literal> = `${TValue}${TSuffix}`;
+/**
+ * Prepend a literal prefix ({@link TPrefix}) to the start of a provided string ({@link TValue}).
+ *
+ * @template TValue - The string to add the prefix to.
+ * @template TPrefix - It extends the {@link Literal} type, and represents the prefix to prepend.
+ *
+ * @example
+ * ```typescript
+ * // A type that prepends 'Hello ' to a string
+ * type Greeting = Suffix<string, 'Hello '>;
+ * const greeting: Greeting = 'Hello Bob'; // This is valid
+ * const farewell: Greeting = 'Bye Bob'; // This is not valid
+ * ```
+ */
+export type Prefix<TValue extends string, TPrefix extends Literal> = `${TPrefix}${TValue}`;
+/**
+ * Creates an indexed object where every key is a string and every value is `T`
+ *
+ * @template T - Value type of the dictionary
+ *
+ * @example
+ * // Dictionary where each key is a string and is bound to a number type value.
+ * const numDict: Dict<number> = {
+ *   'a': 1,
+ *   'b': 2,
+ *   'c': 3
+ * };
+ */
+export type Dict<T> = {
+    [key: string]: T;
+};
+/**
+ * Determines if a string, represented by {@link TValue}, ends with a specific literal ({@link TSuffix}).
+ *
+ * @template TValue - The string to check.
+ * @template TSuffix - A literal which may or may not be at the end of {@link TValue}.
+ *
+ * @remark
+ * To remember easily: `String.prototype.endsWith` method but at type level.
+ *
+ * @example
+ * ```typescript
+ * type Result = EndsWith<"HelloWorld", "World">;
+ * // Output: Constants.True
+ * ```
+ *
+ * ```typescript
+ * type Result = EndsWith<"HelloWorld", "Hello">;
+ * // Output: Constants.False
+ * ```
+ */
+export type EndsWith<TValue extends string, TSuffix extends Literal> = Extends<TValue, `${string}${TSuffix}`>;
+/**
+ * Determines if a string, represented by {@link TValue}, starts with a specific literal ({@link TPrefix}).
+ *
+ * @template TValue - The string to check.
+ * @template TPrefix - A literal which may or may not be at the start of {@link TValue}.
+ *
+ * @remark
+ * To remember easily: `String.prototype.startsWith` method but at type level.
+ *
+ * @example
+ * ```typescript
+ * type IsHelloWorld = StartsWith<"Hello World", "Hello">;
+ * // Output: Constants.True
+ * ```
+ *
+ * @example
+ * ```typescript
+ * type NotHelloWorld = StartsWith<"World Hello", "Hello">;
+ * // Output: Constants.False
+ * ```
+ */
+export type StartsWith<TValue extends string, TPrefix extends Literal> = Extends<TValue, `${TPrefix}${string}`>;
+//# sourceMappingURL=string.d.ts.map

package/dist/utils/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/utils/string.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,KAAK,CAAC,MAAM,SAAS,MAAM,EAAE,UAAU,SAAS,MAAM,IAAI;KACnE,IAAI,IAAI,UAAU,GAAG,MAAM,SAAS,GAAG,MAAM,KAAK,GAAG,IAAI,GAAG,MAAM,MAAM,EAAE,GACvE,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,GAC/B,MAAM,SAAS,EAAE,GACf,EAAE,GACF,CAAC,MAAM,CAAC;CACf,CAAC,UAAU,CAAC,CAAC;AAEd;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,SAAS,OAAO,IAAI,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,SAAS,OAAO,IAAI,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;AAE3F;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAA;CAAE,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,SAAS,OAAO,IAAI,OAAO,CAC5E,MAAM,EACN,GAAG,MAAM,GAAG,OAAO,EAAE,CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,SAAS,OAAO,IAAI,OAAO,CAC9E,MAAM,EACN,GAAG,OAAO,GAAG,MAAM,EAAE,CACtB,CAAC"}

package/dist/utils/tuple.d.ts

@@ -0,0 +1,19 @@
+import type { Literal } from './string';
+/**
+ * Transforms a tuple ({@link TCollection}) into a concatenated string, interlaced with a designated separator character ({@link TSeparator}).
+ *
+ * @template TCollection - Represents the array of elements to be joined.
+ * @template TSeparator - Represents the separator character used to join the elements of {@link TCollection}.
+ *
+ * @example
+ * ```typescript
+ * type R1 = Join<["John", "Doe", "Smith"], ",">; // type R1 = "John,Doe,Smith"
+ * type R2 = Join<[1, 2, 3, 4], "-">; // type R2 = "1-2-3-4"
+ * type R3 = Join<["Foo", "Bar", "Baz"], "," | "-">; // type R3 = "Foo,Bar,Baz" | "Foo-Bar-Baz"
+ * ```
+ */
+export type Join<TCollection extends unknown[], TSeparator extends Literal> = TCollection extends [
+    infer THead extends Literal,
+    ...infer TTail
+] ? TTail['length'] extends 0 ? THead : `${THead}${TSeparator}${Join<TTail, TSeparator>}` : never;
+//# sourceMappingURL=tuple.d.ts.map

package/dist/utils/tuple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tuple.d.ts","sourceRoot":"","sources":["../../src/utils/tuple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,IAAI,CAAC,WAAW,SAAS,OAAO,EAAE,EAAE,UAAU,SAAS,OAAO,IAAI,WAAW,SAAS;IAChG,MAAM,KAAK,SAAS,OAAO;IAC3B,GAAG,MAAM,KAAK;CACf,GACG,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,GACvB,KAAK,GACL,GAAG,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,GACnD,KAAK,CAAC"}