@arkstack/common 0.12.6 → 0.12.7

package/dist/{helpers-D3QVIFSV.d.ts → helpers-DALo42cp.d.ts}

@@ -11,8 +11,29 @@ declare class Encryption {
 //#endregion
 //#region src/utils/hash.d.ts
 declare class Hash {
+  /**
+   * Hash a value using bcrypt
+   *
+   * @param value
+   * @returns
+   */
   static make(value: string): Promise<string>;
+  /**
+   * Verify a value against a hashed value
+   *
+   * @param value
+   * @param hashedValue
+   * @returns
+   */
   static verify(value: string, hashedValue: string): Promise<boolean>;
+  /**
+   * Generate a one-time password (OTP) using TOTP algorithm
+   *
+   * @param digits    The number of digits for the OTP, default is 6.
+   * @param label     A label to identify the OTP, can be an email or phone number.
+   * @param period    Interval of time for which a token is valid, in seconds.
+   * @returns
+   */
   static otp(digits?: number, label?: string, period?: number): TOTP;
   static totp(secret: string, label: string, issuer?: string, period?: number): TOTP;
 }
@@ -22,10 +43,24 @@ type AbstractModelConstructor<TModel = unknown> = abstract new (attributes?: Rec
 type ModelConstructor<TModel extends Model = Model> = AbstractModelConstructor<TModel> & Pick<ModelStatic<TModel>, keyof ModelStatic<TModel>>;
 interface ModelRegistry {}
 type ModelName = Extract<keyof ModelRegistry, string>;
+/**
+ * Determine the number of items to return per page based on the provided query parameters.
+ *
+ * @param query
+ * @returns
+ */
 declare const perPage: (query: {
   limit?: number;
   perPage?: number;
 }) => number;
+/**
+ * Import an application model by name.
+ *
+ * Apps can augment `ModelRegistry` to make `getModel('User')` return `typeof User`.
+ * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
+ *
+ * @param modelName
+ */
 declare function getModel<TName extends ModelName>(modelName: TName): Promise<ModelRegistry[TName]>;
 declare function getModel<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): Promise<TModel>;
 declare const initializeGlobalContext: ({
@@ -37,8 +72,31 @@ declare const initializeGlobalContext: ({
   Response?: any;
   Session?: any;
 }) => Promise<void>;
+/**
+ * Thows to abort the current request
+ *
+ * @param message
+ * @param code
+ * @throws {RequestException}
+ */
 declare const abort: (message?: string, code?: number) => void;
+/**
+ * Asserts that a boolean condition is true.
+ *
+ * @param boolean
+ * @param message
+ * @param code
+ * @throws {RequestException} Throws if the boolean condition is true.
+ */
 declare const abortIf: <T>(boolean: T, message?: string, code?: number) => asserts boolean is T;
+/**
+ * Asserts that a value is not null or undefined.
+ *
+ * @param value
+ * @param message
+ * @param code
+ * @throws {RequestException} Throws if the value is null or undefined.
+ */
 declare const assertFound: <T>(value: T | null | undefined, message: string, code?: number) => asserts value is T;
 //#endregion
 export { abortIf as a, initializeGlobalContext as c, Encryption as d, abort as i, perPage as l, ModelConstructor as n, assertFound as o, ModelRegistry as r, getModel as s, AbstractModelConstructor as t, Hash as u };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /// <reference path="./app.d.ts" />
-import { a as abortIf, c as initializeGlobalContext, d as Encryption, i as abort, l as perPage, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as Hash } from "./helpers-D3QVIFSV.js";
+import { a as abortIf, c as initializeGlobalContext, d as Encryption, i as abort, l as perPage, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as Hash } from "./helpers-DALo42cp.js";
 import { JitiOptions, JitiResolveOptions } from "jiti";
 import { Arkstack } from "@arkstack/contract";
 import pino from "pino";
@@ -9,6 +9,15 @@ import { ChalkInstance } from "chalk";
 declare const bindGracefulShutdown: (shutdown: () => Promise<void> | void, defer?: boolean) => void;
 //#endregion
 //#region src/network.d.ts
+/**
+ * Boots the app using an available port close to the requested port
+ *when requested port is not available
+ *
+ * @param boot
+ * @param preferredPort
+ * @param app
+ * @param defer
+ */
 declare const bootWithDetectedPort: <TApp, TRoutes = unknown, THandler = unknown>(boot: (port: number) => Promise<void>, preferredPort?: number, app?: Arkstack<TApp, TRoutes, THandler>, defer?: boolean) => Promise<void>;
 declare const renderError: ({
   message,
@@ -34,31 +43,130 @@ declare class Console {
   static error: (...args: any[]) => void[];
 }
 declare class Logger {
+  /**
+   * Global verbosity configuration
+   */
   private static verbosity;
   private static isQuiet;
   private static isSilent;
+  /**
+   * Configure global verbosity levels
+   */
   static configure(options?: {
     verbosity?: number;
     quiet?: boolean;
     silent?: boolean;
   }): void;
+  /**
+   * Check if output should be suppressed
+   */
   private static shouldSuppressOutput;
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param value
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
   static twoColumnDetail(name: string, value: string, log?: true, spacer?: string): void;
   static twoColumnDetail(name: string, value: string, log?: false, spacer?: string): [string, string, string];
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param desc
+   * @param width
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
   static describe(name: string, desc: string, width?: number, log?: true): void;
   static describe(name: string, desc: string, width?: number, log?: false): [string, string, string];
+  /**
+   * Logs the message in two columns but allways passing status
+   *
+   * @param name
+   * @param value
+   * @param status
+   * @param exit
+   * @param preserveCol
+   */
   static split(name: string, value: string, status?: 'success' | 'info' | 'error', exit?: boolean, preserveCol?: boolean, spacer?: string): void;
+  /**
+   * Wraps text with chalk
+   *
+   * @param txt
+   * @param color
+   * @param preserveCol
+   * @returns
+   */
   static textFormat(txt: unknown | unknown[], color: (...text: unknown[]) => string, preserveCol?: boolean): string;
+  /**
+   * Logs a success message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static success(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an informational message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static info(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an error message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static error(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a warning message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static warn(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a debug message (only shown with verbosity >= 3)
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static debug<M = any>(msg: M | M[], exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Terminates the process
+   */
   static quiet(): void;
   static chalker(styles: LoggerChalk[]): (input: any) => string;
+  /**
+   * Parse an array formated message and logs it
+   *
+   * @param config
+   * @param joiner
+   * @param log If set to false, string output will be returned and not logged
+   * @param sc color to use ue on split text if : is found
+   */
   static parse(config: LoggerParseSignature, joiner?: string, log?: true, sc?: LoggerChalk): void;
   static parse(config: LoggerParseSignature, joiner?: string, log?: false, sc?: LoggerChalk): string;
+  /**
+   * Ouput formater object or format the output
+   *
+   * @returns
+   */
   static log: LoggerLog;
+  /**
+   * A simple console like output logger
+   *
+   * @returns
+   */
   static console(): typeof Console;
 }
 //#endregion
@@ -72,6 +180,16 @@ type LoggerChalk = keyof ChalkInstance | ChalkInstance | (keyof ChalkInstance)[]
 type LoggerParseSignature = [string, LoggerChalk][];
 type DotPathValue<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? DotPathValue<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
 type DotPath<T> = T extends Primitive ? never : T extends any[] ? never : { [K in keyof T & string]: T[K] extends Primitive ? `${K}` : T[K] extends any[] ? `${K}` : `${K}` | `${K}.${DotPath<T[K]>}` }[keyof T & string];
+/**
+ * Ouput formater object or format the output
+ *
+ * @param config
+ * @param joiner
+ * @param log If set to false, string output will be returned and not logged
+ * @param sc color to use ue on split text if : is found
+ *
+ * @returns
+ */
 interface LoggerLog {
   (): typeof Logger;
   <L extends boolean>(config: string, joiner: LoggerChalk, log?: L, sc?: LoggerChalk): L extends true ? void : string;
@@ -120,13 +238,63 @@ type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof Hook
 type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
 //#endregion
 //#region src/system.d.ts
+/**
+ * Read the .env file
+ *
+ * @param env
+ * @param def
+ * @returns
+ */
 declare const env: GlobalEnv;
+/**
+ * Build the app url
+ *
+ * @param link
+ * @returns
+ */
 declare const appUrl: (link?: string) => string;
 declare const CONFIG_KEY: unique symbol;
+/**
+ * Gets the application configuration.
+ *
+ * @param key             The configuration key to retrieve.
+ * @param defaultValue    The default value to return if the key is not found.
+ * @returns               The configuration value.
+ */
 declare const config: GlobalConfig;
+/**
+ * Gets the current Node environment (development or production).
+ *
+ * @returns
+ */
 declare const nodeEnv: () => "prod" | "dev";
+/**
+ * Gets the output directory for the application based on the current environment.
+ *
+ * @param cwd  The current working directory (optional, defaults to Arkstack.rootDir()).
+ * @returns
+ */
 declare const outputDir: (cwd?: string) => string;
+/**
+ *
+ * Dynamically imports a file at the given path with full TypeScript support,
+ * including `tsconfig.json` path aliases.
+ *
+ * @param filePath - The path to the file to import.
+ * @returns The imported module typed as `T`.
+ *
+ * @example
+ * const config = await importFile<AppConfig>('./config/app.ts')
+ */
 declare const importFile: FileImporter;
+/**
+ * Resolves the default export from a module, handling both CJS and ESM interop.
+ * In CJS modules, the default export is often the module itself (a function or object),
+ * while in ESM the default is nested under the `default` property.
+ *
+ * @param imp - The imported module
+ * @returns The resolved default export
+ */
 declare const interopDefault: <T>(imp: T | {
   default: T;
 }) => T;
@@ -150,8 +318,33 @@ declare class AppException extends Exception {
 declare class RequestException extends AppException {
   statusCode: number;
   constructor(message?: string, statusCode?: number, options?: ErrorOptions);
+  /**
+   * Asserts that a value is not null or undefined.
+   *
+   * @param value
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the value is null or undefined.
+   */
   static assertFound<T>(value: T | null | undefined, message: string, code?: number): asserts value is T;
+  /**
+   * Asserts that a value is not null or undefined.
+   *
+   * @param value
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the value is null or undefined.
+   * @deprecated Use assertFound instead
+   */
   static assertNotEmpty<T>(value: T | null | undefined, message: string, code?: number): asserts value is T;
+  /**
+   * Asserts that a boolean condition is true.
+   *
+   * @param boolean
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the boolean condition is true.
+   */
   static abortIf<T>(boolean: T, message: string, code?: number): asserts boolean is T;
 }
 //#endregion
@@ -188,13 +381,54 @@ declare const logUnhandledError: typeof ErrorHandler.logUnhandledError;
 //#region src/Hook.d.ts
 declare class Hook {
   private static hooks;
+  /**
+   * Hooks define code that should run within defined boundaries to add extra functionalities.
+   *
+   * @param name
+   * @param value
+   */
   static set<N extends HookName>(name: N | (string & {}), hook: HookFor<N>): void;
+  /**
+   * Check if a hook is defined by name
+   *
+   * @param name
+   */
   static has<N extends HookName, P extends HookPositions<N>>(name: N | (string & {}), pos?: P): boolean;
+  /**
+   * Retrieve a defined hook by name
+   *
+   * @param name
+   */
   static get<N extends HookName>(name: N): HookFor<N> | undefined;
+  /**
+   * Retrieve a defined hook by name and position
+   *
+   * @param name
+   * @param pos
+   */
   static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P): HookPos<N, P> | undefined;
+  /**
+   * Retrieve a defined hook by name and position the set args for callback
+   *
+   * @param name
+   * @param pos
+   */
   static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P>): void;
+  /**
+   * Retrieve all defined hooks
+   *
+   * @param name
+   */
   static getAll: () => Record<string, IHook> & HookRegistry;
+  /**
+   * Remove the defined hook
+   *
+   * @param name
+   */
   static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
+  /**
+   * Clear all the defined hooks
+   */
   static clear: () => void;
 }
 //#endregion

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { a as abortIf, c as initializeGlobalContext, d as Encryption, i as abort, l as perPage, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as Hash } from "../helpers-D3QVIFSV.js";
+import { a as abortIf, c as initializeGlobalContext, d as Encryption, i as abort, l as perPage, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as Hash } from "../helpers-DALo42cp.js";
 import { Model } from "arkormx";
 
 //#region src/utils/traits.d.ts
@@ -17,14 +17,32 @@ type CombineClasses<T extends Array<(new () => any) & {
   prototype: Combine<MapClassesToPrototypes<T>>;
 };
 type ResolveTraitLikeArray<T extends Array<Trait | TypeFactory<Trait>>> = CombineClasses<{ [K in keyof T]: ResolveTraitLike<T[K]> }>;
+/**
+ * utility type and function: constructor (function)
+ */
 type Cons<T = any> = new (...args: any[]) => T;
 type ArkormModelCons<T extends Model = Model> = abstract new (...args: any[]) => T;
 type DirectCons<T = any> = Cons<T> | ArkormModelCons<Model>;
 type DirectBase = DirectCons | Model;
+/**
+ * utility type and function: constructor factory (function)
+ */
 type ConsFactory<T extends Cons = Cons, B = any> = (base: B) => T;
+/**
+ * utility type and function: type factory (function)
+ */
 type TypeFactory<T = any> = () => T;
+/**
+ * utility type: map an object type into a bare properties type
+ */
 type Explode<T = any> = { [P in keyof T]: T[P] };
+/**
+ * utility type: convert two arrays of types into an array of union types
+ */
 type MixParams<T1 extends any[], T2 extends any[]> = T1 extends [] ? (T2 extends [] ? [] : T2) : (T2 extends [] ? T1 : (T1 extends [infer H1, ...infer R1] ? (T2 extends [infer H2, ...infer R2] ? [H1 & H2, ...MixParams<R1, R2>] : []) : []));
+/**
+ * API: trait type
+ */
 type TraitDefTypeT = ConsFactory<Cons>;
 type TraitDefTypeST = (Trait | TypeFactory<Trait>)[] | undefined;
 type Trait<T extends TraitDefTypeT = TraitDefTypeT, ST extends TraitDefTypeST = TraitDefTypeST> = {
@@ -33,30 +51,111 @@ type Trait<T extends TraitDefTypeT = TraitDefTypeT, ST extends TraitDefTypeST =
   factory: T;
   superTraits: ST;
 };
+/**
+ * API: generate trait (regular variant)
+ *
+ * @param factory
+ */
 declare function trait<T extends ConsFactory<Cons>>(factory: T): Trait<T, undefined>;
+/**
+ * API: generate trait (super-trait variant)
+ *
+ * @param superTraits
+ * @param factory
+ */
 declare function trait<const ST extends (Trait | TypeFactory<Trait>)[], T extends ConsFactory<Cons, ResolveTraitLikeArray<ST>>>(superTraits: ST, factory: T): Trait<T, ST>;
+/**
+ * utility types: extract factory from a trait
+ */
 type ExtractFactory<T extends Trait> = T extends Trait<ConsFactory<infer C>, TraitDefTypeST> ? C : never;
+/**
+ * utility types: extract supertraits from a trait
+ */
 type ExtractSuperTrait<T extends Trait> = T extends Trait<TraitDefTypeT, infer ST extends TraitDefTypeST> ? ST : never;
+/**
+ * utility type: derive type constructor: merge two constructors
+ */
 type DeriveTraitsConsConsMerge<A extends Cons, B extends Cons> = A extends (new (...args: infer ArgsA) => infer RetA) ? (B extends (new (...args: infer ArgsB) => infer RetB) ? (new (...args: MixParams<ArgsA, ArgsB>) => RetA & RetB) : never) : never;
+/**
+ * utility type: derive type constructor: extract plain constructor
+ */
 type DeriveTraitsConsCons<T extends DirectCons> = new (...args: ConstructorParameters<T>) => InstanceType<T>;
 type DeriveTraitsConsDirectBase<T extends DirectBase> = T extends Model ? new (...args: any[]) => T : T extends DirectCons ? DeriveTraitsConsCons<T> : never;
+/**
+ * utility type: derive type constructor: from trait parts
+ */
 type DeriveTraitsConsTraitParts<C extends Cons, ST extends ((Trait | TypeFactory<Trait>)[] | undefined)> = ST extends undefined ? DeriveTraitsConsCons<C> : ST extends [] ? DeriveTraitsConsCons<C> : DeriveTraitsConsConsMerge<DeriveTraitsConsCons<C>, DeriveTraitsConsAll<ST>>;
+/**
+ * utility type: derive type constructor: from single trait
+ */
 type DeriveTraitsConsTrait<T extends Trait> = DeriveTraitsConsTraitParts<ExtractFactory<T>, ExtractSuperTrait<T>>;
+/**
+ * utility type: derive type constructor: from single trait or trait factory
+ */
 type DeriveTraitsConsOne<T extends (Trait | TypeFactory<Trait>)> = T extends Trait ? DeriveTraitsConsTrait<T> : T extends TypeFactory<Trait> ? DeriveTraitsConsTrait<ReturnType<T>> : never;
-type DeriveTraitsConsAll<T extends (((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase]) | undefined)> = T extends [infer Only extends DirectBase] ? DeriveTraitsConsDirectBase<Only> : T extends [...infer Others extends (Trait | TypeFactory<Trait>)[], infer Last extends DirectBase] ? (Others extends [] ? DeriveTraitsConsDirectBase<Last> : DeriveTraitsConsConsMerge<DeriveTraitsConsAll<Others>, DeriveTraitsConsDirectBase<Last>>) : T extends (Trait | TypeFactory<Trait>)[] ? (T extends [infer First extends (Trait | TypeFactory<Trait>)] ? (DeriveTraitsConsOne<First>) : (T extends [infer First extends (Trait | TypeFactory<Trait>), ...infer Rest extends (Trait | TypeFactory<Trait>)[]] ? (DeriveTraitsConsConsMerge<DeriveTraitsConsOne<First>, DeriveTraitsConsAll<Rest>>) : never)) : never;
+/**
+ * utility type: derive type constructor: from one or more traits or trait factories
+ */
+type DeriveTraitsConsAll<T extends (((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase]) | undefined)> = T extends [infer Only extends DirectBase] ? DeriveTraitsConsDirectBase<Only> : T extends [...infer Others extends (Trait | TypeFactory<Trait>)[], infer Last extends DirectBase] ? (Others extends [] ? DeriveTraitsConsDirectBase<Last> : DeriveTraitsConsConsMerge<DeriveTraitsConsAll<Others>, /* RECURSION */DeriveTraitsConsDirectBase<Last>>) : T extends (Trait | TypeFactory<Trait>)[] ? (T extends [infer First extends (Trait | TypeFactory<Trait>)] ? (DeriveTraitsConsOne<First>) : (T extends [infer First extends (Trait | TypeFactory<Trait>), ...infer Rest extends (Trait | TypeFactory<Trait>)[]] ? (DeriveTraitsConsConsMerge<DeriveTraitsConsOne<First>, DeriveTraitsConsAll<Rest>>) : never)) : never;
+/**
+ * utility type: derive type constructor
+ */
 type DeriveTraitsCons<T extends ((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase])> = DeriveTraitsConsAll<T>;
+/**
+ * utility type: derive type statics: merge two objects with statics
+ */
 type DeriveTraitsStatsConsMerge<T1 extends object, T2 extends object> = T1 & T2;
+/**
+ * utility type: derive type statics: extract plain statics
+ */
 type DeriveTraitsStatsCons<T extends DirectCons> = Explode<T>;
 type DeriveTraitsStatsDirectBase<T extends DirectBase> = T extends Model ? object : T extends DirectCons ? DeriveTraitsStatsCons<T> : never;
+/**
+ * utility type: derive type statics: from trait parts
+ */
 type DeriveTraitsStatsTraitParts<C extends Cons, ST extends ((Trait | TypeFactory<Trait>)[] | undefined)> = ST extends undefined ? DeriveTraitsStatsCons<C> : ST extends [] ? DeriveTraitsStatsCons<C> : DeriveTraitsStatsConsMerge<DeriveTraitsStatsCons<C>, DeriveTraitsStatsAll<ST>>;
+/**
+ * utility type: derive type statics: from single trait
+ */
 type DeriveTraitsStatsTrait<T extends Trait> = DeriveTraitsStatsTraitParts<ExtractFactory<T>, ExtractSuperTrait<T>>;
+/**
+ * utility type: derive type statics: from single trait or trait factory
+ */
 type DeriveTraitsStatsOne<T extends (Trait | TypeFactory<Trait>)> = T extends Trait ? DeriveTraitsStatsTrait<T> : T extends TypeFactory<Trait> ? DeriveTraitsStatsTrait<ReturnType<T>> : never;
-type DeriveTraitsStatsAll<T extends (((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase]) | undefined)> = T extends [infer Only extends DirectBase] ? DeriveTraitsStatsDirectBase<Only> : T extends [...infer Others extends (Trait | TypeFactory<Trait>)[], infer Last extends DirectBase] ? (Others extends [] ? DeriveTraitsStatsDirectBase<Last> : DeriveTraitsStatsConsMerge<DeriveTraitsStatsAll<Others>, DeriveTraitsStatsDirectBase<Last>>) : T extends (Trait | TypeFactory<Trait>)[] ? (T extends [infer First extends (Trait | TypeFactory<Trait>)] ? (DeriveTraitsStatsOne<First>) : (T extends [infer First extends (Trait | TypeFactory<Trait>), ...infer Rest extends (Trait | TypeFactory<Trait>)[]] ? (DeriveTraitsStatsConsMerge<DeriveTraitsStatsOne<First>, DeriveTraitsStatsAll<Rest>>) : never)) : never;
+/**
+ * utility type: derive type statics: from one or more traits or trait factories
+ */
+type DeriveTraitsStatsAll<T extends (((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase]) | undefined)> = T extends [infer Only extends DirectBase] ? DeriveTraitsStatsDirectBase<Only> : T extends [...infer Others extends (Trait | TypeFactory<Trait>)[], infer Last extends DirectBase] ? (Others extends [] ? DeriveTraitsStatsDirectBase<Last> : DeriveTraitsStatsConsMerge<DeriveTraitsStatsAll<Others>, /* RECURSION */DeriveTraitsStatsDirectBase<Last>>) : T extends (Trait | TypeFactory<Trait>)[] ? (T extends [infer First extends (Trait | TypeFactory<Trait>)] ? (DeriveTraitsStatsOne<First>) : (T extends [infer First extends (Trait | TypeFactory<Trait>), ...infer Rest extends (Trait | TypeFactory<Trait>)[]] ? (DeriveTraitsStatsConsMerge<DeriveTraitsStatsOne<First>, DeriveTraitsStatsAll<Rest>>) : never)) : never;
+/**
+ * utility type: derive type statics
+ */
 type DeriveTraitsStats<T extends ((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase])> = DeriveTraitsStatsAll<T>;
+/**
+ * utility type: derive type from one or more traits or trait type factories
+ */
 type DeriveTraits<T extends ((Trait | TypeFactory<Trait>)[] | [...(Trait | TypeFactory<Trait>)[], DirectBase])> = DeriveTraitsCons<T> & DeriveTraitsStats<T>;
+/**
+ * API: derive a class from one or more traits or trait type factories
+ *
+ * @param traits
+ * @returns
+ */
 declare function use<T extends ([Trait | TypeFactory<Trait>, ...(Trait | TypeFactory<Trait>)[]] | [...(Trait | TypeFactory<Trait>)[], DirectBase])>(...traits: T): DeriveTraits<T>;
+/**
+ * internal type: implements trait type
+ */
 type DerivedType<T extends Trait> = InstanceType<ExtractFactory<T>>;
+/**
+ * internal type: implements trait type or trait type factory
+ */
 type Derived<T extends (Trait | TypeFactory<Trait> | Cons)> = T extends TypeFactory<Trait> ? DerivedType<ReturnType<T>> : T extends Trait ? DerivedType<T> : T extends Cons ? T : never;
+/**
+ * API: type guard for checking whether class instance is derived from a trait
+ *
+ * @param instance
+ * @param trait
+ * @returns
+ */
 declare function uses<T extends (Trait | TypeFactory<Trait> | Cons)>(instance: unknown, trait: T): instance is Derived<T>;
 //#endregion
 export { AbstractModelConstructor, Derived, Encryption, Hash, ModelConstructor, ModelRegistry, Trait, abort, abortIf, assertFound, crc32, getModel, initializeGlobalContext, perPage, trait, use, uses };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -42,8 +42,8 @@
   "peerDependencies": {
     "@h3ravel/support": "^0.15.11",
     "arkormx": "^ 2.4.1",
-    "@arkstack/contract": "^0.12.6",
-    "@arkstack/foundry": "^0.12.6"
+    "@arkstack/foundry": "^0.12.7",
+    "@arkstack/contract": "^0.12.7"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",