@arabig/origin 1.0.0

package/types/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright Salar Arab All Rights Reserved.
+ *
+ * @author Salar Arab <salar_arab@outlook.com>
+ */
+/**
+ * Represents a union of the given type, `undefined` and `null`.
+ * @typeParam `T` The type that the union is based on
+ */
+type AoNullish<T> = T | null | undefined;
+/**
+ * Represents a discriminated union of the passed type parameter's possible enteries
+ * based on its keys.
+ * @typeParam `T` The type that the union is based on
+ */
+type AoEntryUnion<T> = {
+    [K in keyof T]: {
+        key: K;
+        value: T[K];
+    };
+}[keyof T];
+/**
+ * Represents a key-value pair in form of a two elements tuple that its first element
+ * is the key and the second one is the value.
+ */
+type AoEntry<T> = [keyof T, T[keyof T]];
+/**
+ * Represents an `object` with loose or typed structure base on given type parameter.
+ * @typeParam `T` The type that determines the structure of the resulting `object`.
+ * If omitted, a complete loose structure will be considered
+ */
+type AoObject<T extends Record<any, any> = any> = T extends any[] ? never : T extends (...p: any[]) => any ? never : unknown extends T ? Record<any, any> : {
+    [K in keyof T]: T[K];
+};
+/**
+ * Represents an `object` that includes a loose minimal structure base on passed type
+ * parameter.
+ * @typeParam `T` The `object` based that forms the minimal structure, if omitted
+ * a complete loose structure will be considered
+ */
+type AoLooseObject<T extends AoObject = AoObject> = AoObject & T;
+/**
+ * Represents a `string` literal union of the given `enum` values.
+ * @typeParam `T`The `enum` type
+ * @typeParam `TDefault` The type that determines the default case of the `enum` values union
+ */
+type AoEnumValue<T extends string, TDefault extends string = never> = `${T}` | TDefault;
+/**
+ * Represents an optional `string` literal union of the given `enum` values.
+ * @typeParam `T`The `enum` type
+ */
+type AoEnumOptionalValue<T extends string> = `${T}` | String;
+/**
+ * Represents either a typed union of specific keys or a plain primitive key
+ * base on given type parameter.
+ * @typeParam `T` The type that determines the keys union or a primitive key if omitted
+ */
+type AoKey<T = unknown> = unknown extends T ? string | number | symbol : keyof T;
+/**
+ * Represents either a typed union of specific keys or a `string` key
+ * base on given type parameter.
+ * @typeParam `T` The type that determines the keys union or a string key if omitted
+ */
+type AoStringKey<T = unknown> = unknown extends T ? string : Exclude<keyof T, number | symbol>;
+/**
+ * Represents either a typed union of specific keys or a plain primitive key
+ * base on given type parameter for all nested types.
+ * @typeParam `T` The type that determines the keys union or a primitive key if omitted
+ * @remarks Using this type for deeply nested types can prove slow compilation time.
+ */
+type AoDeepKey<T = unknown> = unknown extends T ? string | number | symbol : {
+    [K in keyof T]: T[K] extends object ? K | AoDeepKey<T[K]> : K;
+}[keyof T];
+/**
+ * Represents either a typed union of specific keys or a `string` key
+ * base on given type parameter for all nested types.
+ * @typeParam `T` The type that determines the keys union or a `string` key if omitted
+ * @remarks Using this type for deeply nested types can prove slow compilation time.
+ */
+type AoDeepStringKey<T = unknown> = unknown extends T ? string : Exclude<{
+    [K in keyof T]: T[K] extends object ? K | AoDeepKey<T[K]> : K;
+}[keyof T], number | symbol>;
+
+/**
+ * @license
+ * Copyright Salar Arab All Rights Reserved.
+ *
+ * @author Salar Arab <salar_arab@outlook.com>
+ */
+/**
+ * Represents a union of JavaScript primitive data types.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Primitive | Primitive}
+ */
+type AoPrimitive = string | number | boolean | bigint | undefined | null | symbol;
+/**
+ * Represents a union of JavaScript falsy values.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy | Falsy}
+ */
+type AoFalsy = undefined | null | false | 0 | -0 | 0n | "";
+/**
+ * Represents an object that is a CSS declaration block, and exposes style information
+ * and various style-related methods and properties.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration | CSSStyleDeclaration}
+ */
+type AoStyle = Partial<CSSStyleDeclaration>;
+/**
+ * Represents a numeric `string` type
+ */
+type AoDigit = `${number}`;
+/**
+ * Represents a union of the `typeof` keyword result values
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof | typeof}
+ */
+type AoTypeOf = 'string' | 'number' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'bigint';
+
+/**
+* @license
+* Copyright Agin Company All Rights Reserved
+*
+* @author Salar Arab <salar.arab.70@gmail.com>
+*/
+/**
+ * Checks whether the passed type is only assignable to a minimal unbound JS `object`.
+ * @typeParam `T` The type to be checked
+ */
+type AoIsObject<T> = T extends any[] | Function | ((...p: any[]) => any) ? never : T extends Record<any, any> ? T : never;
+/**
+ * Checks whether the passed type is only assignable to a minimal unbound JS `array`.
+ * @typeParam `T` The type to be checked
+ */
+type AoIsArray<T> = T extends any[] ? T : never;
+/**
+ * Checks whether the passed type is only assignable to a minimal callable JS `function`.
+ * @typeParam `T` The type to be checked
+ */
+type AoIsFunction<T> = T extends (...p: any[]) => any ? T : never;
+
+export type { AoDeepKey, AoDeepStringKey, AoDigit, AoEntry, AoEntryUnion, AoEnumOptionalValue, AoEnumValue, AoFalsy, AoIsArray, AoIsFunction, AoIsObject, AoKey, AoLooseObject, AoNullish, AoObject, AoPrimitive, AoStringKey, AoStyle, AoTypeOf };

package/vault/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright Salar Arab All Rights Reserved.
+ *
+ * @author Salar Arab <salar_arab@outlook.com>
+ */
+/**
+ * Represents a uniquely created token-like entity which can be associated with a
+ * corresponding value.
+ *
+ * @remarks
+ * Each `AoToken` instance encapsulates a unique `Symbol` identifier, ensuring
+ * collision-free keying even across modules. The generic type parameter `T` allows
+ * consumers to associate a specific value type with the token, enabling type-safe
+ * retrieval from collections.
+ *
+ * This pattern is especially useful in scenarios like dependency injection,
+ * metadata registries, or strongly typed key-value stores.
+ *
+ * @typeParam `T` The type of value associated with this token.
+ *
+ * @example
+ * ```ts
+ * const BASE_URL_TK = new AoToken<string>("website base URL");
+ *
+ * const collection = new Map();
+ *
+ * function getValue<T>(token: AoToken<T>): T | null {
+      return collection.get(token) ?? null;
+   }
+ *
+ * const value = getValue(BASE_URL_TK); //inferred as string | null
+ * ```
+ */
+declare class AoToken<T> {
+    /**
+     * @remarks Do not use this property in the inheritance, since it reserved for
+     * semantic usage of `T` type parameter.
+     */
+    protected $implicitType?: T;
+    private readonly _identifier;
+    private readonly _description;
+    /**
+     * Creates a new instance with optional given description.
+     * @param description An optional string description
+     */
+    constructor(description?: string | null);
+    /**
+     * @readonly The `symbol` base identifier which is unique for each intance
+     * @remarks It is recommended to use this property for identification or comparsion
+     * purposes.
+     */
+    get identifier(): symbol;
+    /**
+     * @readonly The description about this token instance.
+     * @remarks It is not recommended to use this property for identification or
+     * comparsion purposes, since it's just a simple description about the token instance.
+     * Use the `identifier` property for this matter.
+     */
+    get description(): string;
+    /**
+     * Compares the given `AoToken` with the current instance.
+     * @param comparable The comparing `AoToken` instance
+     * @returns The comparsion result as `boolean`
+     */
+    equals(comparable: AoToken<unknown>): boolean;
+}
+
+/**
+ * @license
+ * Copyright Salar Arab All Rights Reserved.
+ *
+ * @author Salar Arab <salar_arab@outlook.com>
+ */
+
+/**
+ * Represents a type-safe collection that stores and retrieves values using unique,
+ * typed tokens.
+ *
+ * This class utilizes an abstract data structure similar to `Map`, but replaces generic keys
+ * with {@link AoToken} instances to ensure both **uniqueness** and **type safety**. Each token
+ * carries a generic type parameter that enforces the expected value type at compile time,
+ * preventing mismatches and enhancing developer experience.
+ *
+ * Ideal for use cases such as dependency registries, metadata stores, or scoped configuration
+ * systems where strong typing and collision-free keying are critical.
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Abstract_data_type | Abstract data type}
+ *
+ * @typeParam `TValue` Determines the storeable value type range
+ *
+ * @remarks
+ * - Tokens are guaranteed to be unique via their internal `Symbol` identifier.
+ * - Values are type-checked against the token’s generic parameter.
+ * - This structure improves safety and clarity in large-scale, modular applications.
+ *
+ * @example
+ * ```ts
+ * const data = { meta: "data" };
+ *
+ * const DATA_TOKEN = new AoToken<{ meta: "data" }>();
+ *
+ * const collection = new AoVault().store(DATA_TOKEN, data);
+ *
+ * const value = collection.retrieve(DATA_TOKEN); //inferred as { meta: "data" } | null;
+ * ```
+ */
+declare class AoVault<TValue = any> {
+    private readonly _vault;
+    /**
+     * Creates a new instance with optional initial entries.
+     * @param entries The optional initial entries as token-value `tuples`
+     */
+    constructor(entries?: [AoToken<TValue>, TValue][]);
+    /**
+     * Checks if an associated entry exists for the given token.
+     * @param token An instance of {@link AoToken} as querying token
+     * @returns The result of the query as `boolean`
+     */
+    exists(token: AoToken<TValue>): boolean;
+    /**
+     * Stores the given entry base on {@link AoToken}.
+     * @typeParam `T` The type of storing value that must be assignable to {@link AoVault} `TValue` generic type
+     * @param token An instance of {@link AoToken} as querying token
+     * @param value The storing value
+     * @returns The current instance of {@link AoVault}
+     */
+    store<T extends TValue>(token: AoToken<T>, value: T): AoVault<TValue>;
+    /**
+     * Retrieves the associated value base on given {@link AoToken}.
+     * @typeParam `T` The type of retrieving value that must be assignable to {@link AoVault} `TValue` generic type
+     * @param token An instance of {@link AoToken} as querying token
+     * @returns The associated value
+     */
+    retrieve<T extends TValue>(token: AoToken<T>): T | null;
+    /**
+     * Deletes the associated entry base on given {@link AoToken}.
+     * @typeParam `T` The type of deleting value that must be assignable to {@link AoVault} `TValue` generic type
+     * @param token An instance of {@link AoToken} as querying token
+     * @returns The associated value before deleting the entry
+     */
+    delete<T extends TValue>(token: AoToken<T>): T | null;
+}
+
+export { AoToken, AoVault };