@ariestools/sdk 7.0.3

package/dist/_pkg/assert/neutral/assertDefinedEx.d.ts

@@ -0,0 +1,41 @@
+import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts';
+/**
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error if the value is undefined.
+ *
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @param messageFunc - Function that returns a message for the error if expression is undefined
+ * @throws Error with the message returned by messageFunc
+ * @returns The value of the expression (guaranteed to be defined)
+ * @example
+ * ```typescript
+ * // Simple usage with a message function
+ * const value = assertDefinedEx(possiblyUndefined, () => 'Value must be defined')
+ *
+ * // Using with type narrowing
+ * const config: Config | undefined = loadConfig()
+ * const safeConfig = assertDefinedEx(config, () => 'Config failed to load')
+ * // safeConfig is now type Config (not Config | undefined)
+ * ```
+ */
+declare function assertDefinedEx<T>(expr: T | undefined, messageFunc?: AssertExMessageFunc<T>): T;
+/**
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws a custom error if the value is undefined.
+ *
+ * @template T - The type of value to check
+ * @template R - The type of error to throw
+ * @param expr - Expression to be evaluated for being defined
+ * @param errorFunc - Function that returns a custom error instance if expression is undefined
+ * @throws Custom error returned by errorFunc
+ * @returns The value of the expression (guaranteed to be defined)
+ * @example
+ * ```typescript
+ * // Using with a custom error
+ * const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))
+ * ```
+ */
+declare function assertDefinedEx<T, R extends Error>(expr: T | undefined, errorFunc?: AssertExErrorFunc<T, R>): T;
+export { assertDefinedEx };
+//# sourceMappingURL=assertDefinedEx.d.ts.map

package/dist/_pkg/assert/neutral/assertEx.d.ts

@@ -0,0 +1,41 @@
+import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts';
+/**
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error if the expression is falsy.
+ *
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for truthiness
+ * @param messageFunc - Function that returns a message for the error if expression is falsy
+ * @throws Error with the message returned by messageFunc
+ * @returns The value of the expression (guaranteed to be truthy)
+ * @example
+ * ```typescript
+ * // Simple usage with a message function
+ * const value = assertEx(possiblyFalsy, () => 'Value must be truthy')
+ *
+ * // Using with type narrowing
+ * const config: Config | null = loadConfig()
+ * const safeConfig = assertEx(config, () => 'Config failed to load')
+ * // safeConfig is now type Config (not Config | null)
+ * ```
+ */
+declare function assertEx<T>(expr: T | null | undefined, messageFunc?: AssertExMessageFunc<T>): T;
+/**
+ * Asserts that an expression is truthy and returns the value.
+ * Throws a custom error if the expression is falsy.
+ *
+ * @template T - The type of value to check
+ * @template R - The type of error to throw
+ * @param expr - Expression to be evaluated for truthiness
+ * @param errorFunc - Function that returns a custom error instance if expression is falsy
+ * @throws Custom error returned by errorFunc
+ * @returns The value of the expression (guaranteed to be truthy)
+ * @example
+ * ```typescript
+ * // Using with a custom error
+ * const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))
+ * ```
+ */
+declare function assertEx<T, R extends Error>(expr: T | null | undefined, errorFunc?: AssertExErrorFunc<T, R>): T;
+export { assertEx };
+//# sourceMappingURL=assertEx.d.ts.map

package/dist/_pkg/assert/neutral/index.d.ts

@@ -0,0 +1,4 @@
+export * from './assertDefinedEx.ts';
+export * from './assertEx.ts';
+export type * from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/assert/neutral/index.mjs

@@ -0,0 +1,30 @@
+// src/assertDefinedEx.ts
+function assertDefinedEx(expr, func) {
+  if (expr !== void 0) return expr;
+  if (typeof func === "function") {
+    const errorOrMessage = func(expr);
+    throw typeof errorOrMessage === "string" ? new Error(errorOrMessage) : errorOrMessage;
+  }
+  if (func !== void 0) {
+    throw new Error("Invalid assertDefinedEx usage: second argument must be a function or undefined");
+  }
+  throw new Error("Assertion failed: value is undefined");
+}
+
+// src/assertEx.ts
+function assertEx(expr, func) {
+  if (expr !== void 0 && expr !== null && expr !== false && expr !== 0 && expr !== "" && expr !== 0n) return expr;
+  if (typeof func === "function") {
+    const errorOrMessage = func(expr);
+    throw typeof errorOrMessage === "string" ? new Error(errorOrMessage) : errorOrMessage;
+  }
+  if (func !== void 0) {
+    throw new Error("Invalid assertEx usage: second argument must be a function or undefined");
+  }
+  throw new Error("Assertion failed");
+}
+export {
+  assertDefinedEx,
+  assertEx
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/assert/neutral/model.d.ts

@@ -0,0 +1,2 @@
+export type * from './types.ts';
+//# sourceMappingURL=model.d.ts.map

package/dist/_pkg/assert/neutral/model.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=model.mjs.map

package/dist/_pkg/assert/neutral/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @internal
+ * A function that takes a possibly null or undefined value and returns an error message string.
+ * Used in assertion functions to provide custom error messages.
+ *
+ * @internal
+ * @template T - The type of value being asserted
+ * @param value - The value being asserted (may be null or undefined)
+ * @returns A string message to be used in the error thrown by the assertion
+ * @example
+ * ```typescript
+ * const messageFunc: AssertExMessageFunc<User> = (user) =>
+ *   `User ${user ? user.id : 'unknown'} is not valid or accessible`
+ * ```
+ */
+export type AssertExMessageFunc<T> = (value?: T | null) => string;
+/**
+ * A function that takes a possibly null or undefined value and returns a custom error instance.
+ * Used in assertion functions to provide specific error types with custom properties.
+ *
+ * @internal
+ * @template T - The type of value being asserted
+ * @template R - The specific error type to be returned, must extend Error
+ * @param value - The value being asserted (may be null or undefined)
+ * @returns An instance of the custom error type
+ * @example
+ * ```typescript
+ * const errorFunc: AssertExErrorFunc<User, UserNotFoundError> = (user) =>
+ *   new UserNotFoundError(`User ${user?.id || 'unknown'} not found`, {
+ *     userId: user?.id,
+ *     timestamp: new Date()
+ *   })
+ * ```
+ */
+export type AssertExErrorFunc<T, R extends Error> = (value?: T | null) => R;
+//# sourceMappingURL=types.d.ts.map

package/dist/_pkg/base/neutral/Base.d.ts

@@ -0,0 +1,53 @@
+import type { Logger } from '../../logger/neutral/index.ts';
+import type { EmptyObject } from '../../object/neutral/index.ts';
+import type { Meter, MeterProvider, Tracer, TracerProvider } from '@opentelemetry/api';
+/** Branded string type representing a class name used for global instance tracking. */
+export type BaseClassName = string & {
+    __baseClassName: true;
+};
+/** Common parameter fields available to all Base instances (logger, meter, tracer). */
+export interface BaseParamsFields {
+    logger?: Logger;
+    meterProvider?: MeterProvider;
+    traceProvider?: TracerProvider;
+}
+/** Parameters for constructing a Base instance, combining BaseParamsFields with optional additional params. */
+export type BaseParams<TAdditionalParams extends EmptyObject = EmptyObject> = TAdditionalParams & BaseParamsFields;
+/**
+ * Abstract base class providing logging, telemetry, and global instance tracking with WeakRef-based GC.
+ * @typeParam TParams - The parameter type, extending BaseParams
+ */
+export declare abstract class Base<TParams extends BaseParams = BaseParams> {
+    static defaultLogger?: Logger;
+    static readonly globalInstances: Record<BaseClassName, WeakRef<Base>[]>;
+    static readonly globalInstancesCountHistory: Record<BaseClassName, number[]>;
+    private static _historyInterval;
+    private static _historyTime;
+    private static _historyTimeout?;
+    private static _lastGC;
+    private static _maxGcFrequency;
+    private _params;
+    constructor(params: BaseParams<TParams>);
+    static get historyInterval(): number;
+    static set historyInterval(value: number);
+    static get historyTime(): number;
+    static set historyTime(value: number);
+    static get maxGcFrequency(): number;
+    static set maxGcFrequency(value: number);
+    static get maxHistoryDepth(): number;
+    get logger(): Logger | undefined;
+    get meter(): Meter | undefined;
+    get params(): BaseParams<TParams>;
+    get tracer(): Tracer | undefined;
+    static gc(force?: boolean): void;
+    static gc(className: BaseClassName): void;
+    static instanceCount(className: BaseClassName): number;
+    static instanceCounts(): Record<BaseClassName, number>;
+    static startHistory(): void;
+    static stopHistory(): void;
+    private static addToHistory;
+    private static gcAll;
+    private static gcClass;
+    private recordInstance;
+}
+//# sourceMappingURL=Base.d.ts.map

package/dist/_pkg/base/neutral/UniqueBase.d.ts

@@ -0,0 +1,10 @@
+import type { BaseParams } from './Base.ts';
+import { Base } from './Base.ts';
+/** Base class that registers itself as globally unique, preventing duplicate module instances. */
+export declare abstract class UniqueBase<TParams extends BaseParams = BaseParams> extends Base<TParams> {
+    static readonly uniqueDomain = "xy";
+    static readonly uniqueName: string;
+    static readonly uniqueNameXyo: string;
+    constructor(params: BaseParams<TParams>);
+}
+//# sourceMappingURL=UniqueBase.d.ts.map

package/dist/_pkg/base/neutral/globallyUnique.d.ts

@@ -0,0 +1,21 @@
+declare global {
+    interface ImportMeta {
+        url: string;
+    }
+    var xylabs: {
+        unique: Record<string, unknown>;
+        uniqueDisabled?: boolean;
+    };
+}
+/** Disables global uniqueness checks, allowing duplicate registrations without throwing. */
+export declare const disableGloballyUnique: () => void;
+/**
+ * Registers a value as globally unique under the given name and domain.
+ * Throws if a different value is already registered under the same key.
+ * @param name - The unique name or symbol
+ * @param value - The value to register
+ * @param domain - The namespace domain (default 'global')
+ * @returns The fully qualified unique name
+ */
+export declare const globallyUnique: (name: string | symbol, value: unknown, domain?: string) => string;
+//# sourceMappingURL=globallyUnique.d.ts.map

package/dist/_pkg/base/neutral/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Base.ts';
+export * from './globallyUnique.ts';
+export * from './UniqueBase.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/base/neutral/index.mjs

@@ -0,0 +1,164 @@
+// src/Base.ts
+import { assertEx } from "../../assert/neutral/index.mjs";
+var DEFAULT_HISTORY_INTERVAL = 1e3 * 5;
+var DEFAULT_HISTORY_TIME = 60 * 60 * 1e3;
+var MAX_GC_FREQUENCY = 1e3 * 60;
+var MIN_GC_FREQUENCY = 1e3;
+var MIN_HISTORY_INTERVAL = 1e3;
+var Base = class _Base {
+  static defaultLogger;
+  static globalInstances = {};
+  static globalInstancesCountHistory = {};
+  static _historyInterval = DEFAULT_HISTORY_INTERVAL;
+  static _historyTime = DEFAULT_HISTORY_TIME;
+  static _historyTimeout;
+  static _lastGC = 0;
+  static _maxGcFrequency = MAX_GC_FREQUENCY;
+  _params;
+  constructor(params) {
+    this._params = params;
+    params?.logger?.debug(`Base constructed [${this.constructor.name}]`);
+    this.recordInstance();
+  }
+  static get historyInterval() {
+    return this._historyInterval;
+  }
+  static set historyInterval(value) {
+    assertEx(value <= this.historyTime, () => `historyInterval [${value}] must be less than or equal to historyTime [${this.historyTime}]`);
+    this._historyInterval = Math.max(value, MIN_HISTORY_INTERVAL);
+  }
+  static get historyTime() {
+    return this._historyTime;
+  }
+  static set historyTime(value) {
+    assertEx(value >= this.historyInterval, () => `historyTime [${value}] must be greater than or equal to historyInterval [${this.historyInterval}]`);
+    this._historyInterval = value;
+  }
+  static get maxGcFrequency() {
+    return this._maxGcFrequency;
+  }
+  static set maxGcFrequency(value) {
+    this._maxGcFrequency = Math.max(value, MIN_GC_FREQUENCY);
+  }
+  static get maxHistoryDepth() {
+    return Math.floor(this.historyTime / this.historyInterval);
+  }
+  get logger() {
+    return this.params?.logger ?? _Base.defaultLogger;
+  }
+  get meter() {
+    return this.params?.meterProvider?.getMeter(this.constructor.name);
+  }
+  get params() {
+    return this._params;
+  }
+  get tracer() {
+    return this.params?.traceProvider?.getTracer(this.constructor.name);
+  }
+  static gc(classNameOrForce = false) {
+    if (typeof classNameOrForce === "string") {
+      this.gcClass(classNameOrForce);
+    } else {
+      if (classNameOrForce || Date.now() - this._lastGC > this._maxGcFrequency) {
+        this.gcAll();
+      }
+    }
+  }
+  static instanceCount(className) {
+    return this.globalInstances[className]?.length ?? 0;
+  }
+  static instanceCounts() {
+    this.gc();
+    const result = {};
+    for (const [className, instances] of Object.entries(this.globalInstances)) result[className] = instances.length;
+    return result;
+  }
+  static startHistory() {
+    if (this._historyTimeout !== void 0) {
+      this.stopHistory();
+    }
+    const timeoutHandler = () => {
+      if (this._historyTimeout === void 0) {
+        return;
+      }
+      this.addToHistory();
+      this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval);
+    };
+    this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval);
+  }
+  static stopHistory() {
+    if (this._historyTimeout === void 0) {
+      return;
+    }
+    clearTimeout(this._historyTimeout);
+    this._historyTimeout = void 0;
+  }
+  static addToHistory() {
+    const counts = this.instanceCounts();
+    for (const className of Object.keys(this.globalInstances)) {
+      this.globalInstancesCountHistory[className] = this.globalInstancesCountHistory[className]?.slice(-this.maxHistoryDepth) ?? [];
+      this.globalInstancesCountHistory[className].push(counts[className]);
+    }
+  }
+  static gcAll() {
+    for (const className of Object.keys(this.globalInstances)) {
+      this.gcClass(className);
+    }
+  }
+  static gcClass(className) {
+    this.globalInstances[className] = this.globalInstances[className]?.filter((ref) => ref.deref() !== null) ?? [];
+  }
+  recordInstance() {
+    const baseClassName = this.constructor.name;
+    const instanceArray = _Base.globalInstances[baseClassName] ?? [];
+    instanceArray.push(new WeakRef(this));
+    _Base.globalInstances[baseClassName] = instanceArray;
+  }
+};
+
+// src/globallyUnique.ts
+var xyoGlobal = () => {
+  if (globalThis.xylabs === void 0) {
+    Reflect.set(globalThis, "xylabs", {});
+  }
+  return globalThis.xylabs;
+};
+var disableGloballyUnique = () => {
+  xyoGlobal().uniqueDisabled = true;
+};
+var globallyUnique = (name, value, domain = "global") => {
+  const uniqueName = [domain, ...domain === "bundle" ? [name] : [import.meta.url, name]].join(":");
+  if (xyoGlobal().uniqueDisabled !== true) {
+    const xylabs = xyoGlobal();
+    xylabs.unique ??= {};
+    const unique = xylabs.unique;
+    if (unique[uniqueName] === void 0) {
+      unique[uniqueName] = value;
+    } else {
+      if (unique[uniqueName] !== value) {
+        throw new Error(
+          `Global unique item ${uniqueName} already defined.  Make sure you are not importing two versions of the package that contains this item`
+        );
+      }
+    }
+  }
+  return uniqueName;
+};
+
+// src/UniqueBase.ts
+var UniqueBase = class extends Base {
+  static uniqueDomain = "xy";
+  static uniqueName = globallyUnique(this.name, this, this.uniqueDomain);
+  // TODO: Remove xyo domain version when old xyo versions are no longer needed
+  static uniqueNameXyo = globallyUnique(this.name, this, "xyo");
+  constructor(params) {
+    super(params);
+  }
+};
+export {
+  Base,
+  UniqueBase,
+  disableGloballyUnique,
+  globallyUnique
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/base/neutral/model.d.ts

@@ -0,0 +1,2 @@
+export type { BaseClassName, BaseParams, BaseParamsFields, } from './Base.ts';
+//# sourceMappingURL=model.d.ts.map

package/dist/_pkg/base/neutral/model.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=model.mjs.map

package/dist/_pkg/creatable/neutral/AbstractCreatable.d.ts

@@ -0,0 +1,123 @@
+import type { EventData } from '../../events/neutral/index.ts';
+import { BaseEmitter } from '../../events/neutral/index.ts';
+import { type Logger } from '../../logger/neutral/index.ts';
+import type { Promisable } from '../../promise/neutral/index.ts';
+import type { SpanConfig } from '../../telemetry/neutral/index.ts';
+import { type Creatable, type CreatableFactory } from './Creatable.ts';
+import type { CreatableInstance, CreatableName, CreatableParams, CreatableStatus, Labels, RequiredCreatableParams } from './model/index.ts';
+/**
+ * Base class for objects that follow an asynchronous creation and lifecycle pattern.
+ * Instances must be created via the static `create` method rather than direct construction.
+ * Provides start/stop lifecycle management with status tracking and telemetry support.
+ */
+export declare class AbstractCreatable<TParams extends CreatableParams = CreatableParams, TEventData extends EventData = EventData> extends BaseEmitter<Partial<TParams & RequiredCreatableParams>, TEventData> {
+    /** Optional default logger for this instance. */
+    defaultLogger?: Logger;
+    protected _startPromise: Promisable<boolean> | undefined;
+    private _status;
+    private _statusMutex;
+    private _validatedParams?;
+    constructor(key: unknown, params: Partial<TParams & RequiredCreatableParams>);
+    /** The name identifier for this creatable instance. */
+    get name(): CreatableName;
+    /** The validated and merged parameters for this instance. */
+    get params(): TParams & RequiredCreatableParams;
+    /** Whether this instance can be started (must be in 'created' or 'stopped' status). */
+    get startable(): boolean;
+    /** The current lifecycle status of this instance, or null if not yet initialized. */
+    get status(): CreatableStatus | null;
+    /** The status reporter used to broadcast lifecycle changes. */
+    get statusReporter(): import("./model/CreatableStatusReporter.ts").CreatableStatusReporter<void> | undefined;
+    /**
+     * Asynchronously creates a new instance by processing params, constructing,
+     * and running both static and instance createHandlers.
+     * @param inParams - Optional partial parameters to configure the instance
+     * @returns The fully initialized instance
+     */
+    static create<T extends CreatableInstance>(this: Creatable<T>, inParams?: Partial<T['params']>): Promise<T>;
+    /**
+     * Static hook called during creation to perform additional initialization.
+     * Override in subclasses to customize post-construction setup.
+     * @param instance - The newly constructed instance
+     * @returns The instance, potentially modified
+     */
+    static createHandler<T extends CreatableInstance>(this: Creatable<T>, instance: T): Promisable<T>;
+    /**
+     * Static hook called during creation to validate and transform params.
+     * Override in subclasses to add default values or validation.
+     * @param params - The raw partial params provided to `create`
+     * @returns The processed params ready for construction
+     */
+    static paramsHandler<T extends CreatableInstance>(this: Creatable<T>, params?: Partial<T['params']>): Promisable<T['params']>;
+    /** Instance-level creation hook. Override in subclasses to perform setup after construction. */
+    createHandler(): Promisable<void>;
+    /**
+     * Validates and returns the merged params, ensuring required fields are present.
+     * Override in subclasses to add custom validation logic.
+     * @param params - The raw partial params to validate
+     * @returns The validated params
+     */
+    paramsValidator(params: Partial<TParams & RequiredCreatableParams>): TParams & RequiredCreatableParams;
+    /**
+     * Executes a function within a telemetry span.
+     * @param name - The span name
+     * @param fn - The function to execute within the span
+     */
+    span<T>(name: string, fn: () => T): T;
+    /**
+     * Executes an async function within a telemetry span.
+     * @param name - The span name
+     * @param fn - The async function to execute within the span
+     * @param config - Optional span configuration
+     */
+    spanAsync<T>(name: string, fn: () => Promise<T>, config?: SpanConfig): Promise<T>;
+    /**
+     * Starts the instance, transitioning through 'starting' to 'started' status.
+     * Thread-safe via mutex. Returns true if already started or started successfully.
+     */
+    start(): Promise<boolean>;
+    /**
+     * Checks whether this instance is currently started.
+     * Takes an action if not started, based on the notStartedAction parameter.
+     * @param notStartedAction - What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
+     * @returns True if started, false otherwise
+     */
+    started(notStartedAction?: 'error' | 'throw' | 'warn' | 'log' | 'none'): boolean;
+    /**
+     * Async version of `started` that can optionally auto-start the instance.
+     * @param notStartedAction - What to do if not started and auto-start is disabled
+     * @param tryStart - If true, attempts to start the instance automatically
+     * @returns True if the instance is or becomes started
+     */
+    startedAsync(notStartedAction?: 'error' | 'throw' | 'warn' | 'log' | 'none', tryStart?: boolean): Promise<boolean>;
+    /**
+     * Stops the instance, transitioning through 'stopping' to 'stopped' status.
+     * Thread-safe via mutex. Returns true if already stopped or stopped successfully.
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Asserts that the given function has not been overridden in a subclass.
+     * Used to enforce the handler pattern (override `startHandler` not `start`).
+     */
+    protected _noOverride(functionName?: string): void;
+    /** Sets the lifecycle status and reports it via the status reporter. */
+    protected setStatus(value: Exclude<CreatableStatus, 'error'>, progress?: number): void;
+    protected setStatus(value: Extract<CreatableStatus, 'error'>, error?: Error): void;
+    /** Override in subclasses to define start behavior. Throw an error on failure. */
+    protected startHandler(): Promisable<void>;
+    /** Override in subclasses to define stop behavior. Throw an error on failure. */
+    protected stopHandler(): Promisable<void>;
+}
+/**
+ * Extends AbstractCreatable with a static `factory` method for creating
+ * pre-configured CreatableFactory instances.
+ */
+export declare class AbstractCreatableWithFactory<TParams extends CreatableParams = CreatableParams, TEventData extends EventData = EventData> extends AbstractCreatable<TParams, TEventData> {
+    /**
+     * Creates a factory that produces instances of this class with pre-configured params and labels.
+     * @param params - Default parameters for instances created by the factory
+     * @param labels - Labels to assign to created instances
+     */
+    static factory<T extends CreatableInstance>(this: Creatable<T>, params?: Partial<T['params']>, labels?: Labels): CreatableFactory<T>;
+}
+//# sourceMappingURL=AbstractCreatable.d.ts.map

package/dist/_pkg/creatable/neutral/Creatable.d.ts

@@ -0,0 +1,49 @@
+import type { Logger } from '../../logger/neutral/index.ts';
+import type { Promisable } from '../../promise/neutral/index.ts';
+import type { AbstractCreatable } from './AbstractCreatable.ts';
+import type { CreatableInstance, CreatableParams, Labels, RequiredCreatableParams } from './model/index.ts';
+/**
+ * A factory interface for creating instances of a Creatable with pre-configured parameters.
+ * Unlike the full Creatable, this only exposes the `create` method.
+ */
+export interface CreatableFactory<T extends CreatableInstance = CreatableInstance> extends Omit<Creatable<T>, 'create' | 'createHandler' | 'paramsHandler' | 'defaultLogger' | 'factory'> {
+    /** Creates a new instance, merging the provided params with the factory's defaults. */
+    create(this: CreatableFactory<T>, params?: Partial<T['params']>): Promise<T>;
+}
+/**
+ * Static interface for classes that support asynchronous creation.
+ * Provides the `create`, `createHandler`, and `paramsHandler` static methods
+ * used to construct instances through the creatable lifecycle.
+ */
+export interface Creatable<T extends CreatableInstance = CreatableInstance> {
+    /** Optional default logger shared across instances created by this class. */
+    defaultLogger?: Logger;
+    /** Constructs a new raw instance. Should not be called directly; use `create` instead. */
+    new (key: unknown, params: Partial<CreatableParams>): T & AbstractCreatable<T['params']>;
+    /** Asynchronously creates and initializes a new instance with the given params. */
+    create<T extends CreatableInstance>(this: Creatable<T>, params?: Partial<T['params']>): Promise<T>;
+    /** Hook called after construction to perform additional initialization on the instance. */
+    createHandler<T extends CreatableInstance>(this: Creatable<T>, instance: T): Promisable<T>;
+    /** Hook called to validate and transform params before instance construction. */
+    paramsHandler<T extends CreatableInstance>(this: Creatable<T>, params?: Partial<T['params']>): Promisable<T['params'] & RequiredCreatableParams>;
+}
+/** Extends Creatable with a `factory` method that produces pre-configured CreatableFactory instances. */
+export interface CreatableWithFactory<T extends CreatableInstance = CreatableInstance> extends Creatable<T> {
+    /** Creates a factory with the given default params and labels. */
+    factory<T extends CreatableInstance>(this: Creatable<T>, params?: Partial<T['params']>, labels?: Labels): CreatableFactory<T>;
+}
+/**
+ * Class annotation to be used to decorate Modules which support
+ * an asynchronous creation pattern
+ * @returns The decorated Module requiring it implement the members
+ * of the CreatableModule as statics properties/methods
+ */
+export declare function creatable<T extends CreatableInstance>(): <U extends Creatable<T>>(constructor: U) => void;
+/**
+ * Class annotation to be used to decorate Modules which support
+ * an asynchronous creation factory pattern
+ * @returns The decorated Module requiring it implement the members
+ * of the CreatableModule as statics properties/methods
+ */
+export declare function creatableFactory(): <U extends CreatableFactory>(constructor: U) => void;
+//# sourceMappingURL=Creatable.d.ts.map

package/dist/_pkg/creatable/neutral/Factory.d.ts

@@ -0,0 +1,28 @@
+import { type Creatable, type CreatableFactory } from './Creatable.ts';
+import type { CreatableInstance, Labels } from './model/index.ts';
+/**
+ * A concrete factory that wraps a Creatable class with default parameters and labels.
+ * Instances are created by merging caller-provided params over the factory defaults.
+ */
+export declare class Factory<T extends CreatableInstance = CreatableInstance> implements CreatableFactory<T> {
+    /** The Creatable class this factory delegates creation to. */
+    creatable: Creatable<T>;
+    /** Default parameters merged into every `create` call. */
+    defaultParams?: Partial<T['params']>;
+    /** Labels identifying resources created by this factory. */
+    labels?: Labels;
+    constructor(creatable: Creatable<T>, params?: Partial<T['params']>, labels?: Labels);
+    /**
+     * Creates a new Factory instance with the given default params and labels.
+     * @param creatableModule - The Creatable class to wrap
+     * @param params - Default parameters for new instances
+     * @param labels - Labels to assign to created instances
+     */
+    static withParams<T extends CreatableInstance>(creatableModule: Creatable<T>, params?: Partial<T['params']>, labels?: Labels): Factory<T>;
+    /**
+     * Creates a new instance, merging the provided params over the factory defaults.
+     * @param params - Optional parameters to override the factory defaults
+     */
+    create(params?: Partial<T['params']>): Promise<T>;
+}
+//# sourceMappingURL=Factory.d.ts.map

package/dist/_pkg/creatable/neutral/index.d.ts

@@ -0,0 +1,5 @@
+export * from './AbstractCreatable.ts';
+export * from './Creatable.ts';
+export * from './Factory.ts';
+export * from './model/index.ts';
+//# sourceMappingURL=index.d.ts.map