@xylabs/creatable

v5.0.90

Published

4 days ago

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

0High
0Medium
0Low

xyo

@xylabs/creatable

![logo][]

[![main-build][]][main-build-link] [![npm-badge][]][npm-link] [![npm-downloads-badge][]][npm-link] [![jsdelivr-badge][]][jsdelivr-link] ![npm-license-badge][] [![codacy-badge][]][codacy-link] [![codeclimate-badge][]][codeclimate-link] [![snyk-badge][]][snyk-link] [![socket-badge][]][socket-link]

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Reference

@xylabs/creatable

Classes

| Class | Description | | ------ | ------ | | AbstractCreatable | 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. | | AbstractCreatableWithFactory | Extends AbstractCreatable with a static factory method for creating pre-configured CreatableFactory instances. | | Factory | 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. |

Interfaces

| Interface | Description | | ------ | ------ | | CreatableFactory | A factory interface for creating instances of a Creatable with pre-configured parameters. Unlike the full Creatable, this only exposes the create method. | | Creatable | Static interface for classes that support asynchronous creation. Provides the create, createHandler, and paramsHandler static methods used to construct instances through the creatable lifecycle. | | CreatableWithFactory | Extends Creatable with a factory method that produces pre-configured CreatableFactory instances. | | CreatableInstance | Represents a created instance with a managed lifecycle (start/stop) and event emission. | | RequiredCreatableParams | The minimum required parameters for constructing a creatable. | | CreatableParams | Parameters for creating a creatable instance, combining required params with emitter params. | | CreatableStatusReporter | Reports status changes for a creatable, supporting progress tracking and error reporting. | | Labels | Object used to represent labels identifying a resource. | | WithLabels | Interface for objects that have labels. | | WithOptionalLabels | Interface for objects that have labels. |

Type Aliases

| Type Alias | Description | | ------ | ------ | | CreatableName | A branded string type used as the name identifier for creatables. | | StandardCreatableStatus | The standard lifecycle statuses a creatable can transition through. | | CreatableStatus | A creatable's status, optionally extended with additional custom status values. |

Functions

| Function | Description | | ------ | ------ | | creatable | Class annotation to be used to decorate Modules which support an asynchronous creation pattern | | creatableFactory | Class annotation to be used to decorate Modules which support an asynchronous creation factory pattern | | hasAllLabels | Returns true if the source object has all the labels from the required set |

classes

AbstractCreatable

@xylabs/creatable

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.

Extends

BaseEmitter<Partial<TParams & RequiredCreatableParams>, TEventData>

Extended by

AbstractCreatableWithFactory

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TParams extends CreatableParams | CreatableParams | | TEventData extends EventData | EventData |

Constructors

Constructor

new AbstractCreatable<TParams, TEventData>(key: unknown, params: Partial<TParams & RequiredCreatableParams>): AbstractCreatable<TParams, TEventData>;

Parameters

| Parameter | Type | | ------ | ------ | | key | unknown | | params | Partial<TParams & RequiredCreatableParams> |

Returns

AbstractCreatable<TParams, TEventData>

Overrides

BaseEmitter<Partial<TParams & RequiredCreatableParams>, TEventData>.constructor

Properties

| Property | Modifier | Type | Description | Inherited from | | ------ | ------ | ------ | ------ | ------ | | defaultLogger? | static | Logger | - | BaseEmitter.defaultLogger | | globalInstances | readonly | Record<BaseClassName, WeakRef<Base>[]> | - | BaseEmitter.globalInstances | | globalInstancesCountHistory | readonly | Record<BaseClassName, number[]> | - | BaseEmitter.globalInstancesCountHistory | | defaultLogger? | public | Logger | Optional default logger for this instance. | - | | _startPromise | protected | Promisable<boolean> | undefined | - | - | | eventData | public | TEventData | Type-level reference to the event data shape for external type queries. | BaseEmitter.eventData |

Accessors

historyInterval

Get Signature

get static historyInterval(): number;

Returns

number

Set Signature

set static historyInterval(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

BaseEmitter.historyInterval

historyTime

Get Signature

get static historyTime(): number;

Returns

number

Set Signature

set static historyTime(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

BaseEmitter.historyTime

maxGcFrequency

Get Signature

get static maxGcFrequency(): number;

Returns

number

Set Signature

set static maxGcFrequency(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

BaseEmitter.maxGcFrequency

maxHistoryDepth

Get Signature

get static maxHistoryDepth(): number;

Returns

number

Inherited from

BaseEmitter.maxHistoryDepth

logger

Get Signature

get logger(): Logger | undefined;

Returns

Logger | undefined

Inherited from

BaseEmitter.logger

meter

Get Signature

get meter(): Meter | undefined;

Returns

Meter | undefined

Inherited from

BaseEmitter.meter

tracer

Get Signature

get tracer(): Tracer | undefined;

Returns

Tracer | undefined

Inherited from

BaseEmitter.tracer

name

Get Signature

get name(): CreatableName;

The name identifier for this creatable instance.

Returns

CreatableName

params

Get Signature

get params(): TParams & RequiredCreatableParams<void>;

The validated and merged parameters for this instance.

Returns

TParams & RequiredCreatableParams<void>

Overrides

BaseEmitter.params

startable

Get Signature

get startable(): boolean;

Whether this instance can be started (must be in 'created' or 'stopped' status).

Returns

boolean

status

Get Signature

get status(): CreatableStatus | null;

The current lifecycle status of this instance, or null if not yet initialized.

Returns

CreatableStatus | null

statusReporter

Get Signature

get statusReporter(): 
  | CreatableStatusReporter<void>
  | undefined;

The status reporter used to broadcast lifecycle changes.

Returns

| CreatableStatusReporter<void> | undefined

Methods

gc()

Call Signature

static gc(force?: boolean): void;

Parameters

| Parameter | Type | | ------ | ------ | | force? | boolean |

Returns

void

Inherited from

BaseEmitter.gc

Call Signature

static gc(className: BaseClassName): void;

Parameters

| Parameter | Type | | ------ | ------ | | className | BaseClassName |

Returns

void

Inherited from

BaseEmitter.gc

instanceCount()

static instanceCount(className: BaseClassName): number;

Parameters

| Parameter | Type | | ------ | ------ | | className | BaseClassName |

Returns

number

Inherited from

BaseEmitter.instanceCount

instanceCounts()

static instanceCounts(): Record<BaseClassName, number>;

Returns

Record<BaseClassName, number>

Inherited from

BaseEmitter.instanceCounts

startHistory()

static startHistory(): void;

Returns

void

Inherited from

BaseEmitter.startHistory

stopHistory()

static stopHistory(): void;

Returns

void

Inherited from

BaseEmitter.stopHistory

create()

static create<T>(this: Creatable<T>, inParams?: Partial<T["params"]>): Promise<T>;

Asynchronously creates a new instance by processing params, constructing, and running both static and instance createHandlers.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | Creatable<T> | - | | inParams | Partial<T["params"]> | Optional partial parameters to configure the instance |

Returns

Promise<T>

The fully initialized instance

createHandler()

static createHandler<T>(this: Creatable<T>, instance: T): Promisable<T>;

Static hook called during creation to perform additional initialization. Override in subclasses to customize post-construction setup.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | Creatable<T> | - | | instance | T | The newly constructed instance |

Returns

Promisable<T>

The instance, potentially modified

paramsHandler()

static paramsHandler<T>(this: Creatable<T>, params?: Partial<T["params"]>): Promisable<T["params"]>;

Static hook called during creation to validate and transform params. Override in subclasses to add default values or validation.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | Creatable<T> | - | | params | Partial<T["params"]> | The raw partial params provided to create |

Returns

Promisable<T["params"]>

The processed params ready for construction

createHandler()

createHandler(): Promisable<void>;

Instance-level creation hook. Override in subclasses to perform setup after construction.

Returns

Promisable<void>

paramsValidator()

paramsValidator(params: Partial<TParams & RequiredCreatableParams>): TParams & RequiredCreatableParams<void>;

Validates and returns the merged params, ensuring required fields are present. Override in subclasses to add custom validation logic.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | params | Partial<TParams & RequiredCreatableParams> | The raw partial params to validate |

Returns

TParams & RequiredCreatableParams<void>

The validated params

span()

span<T>(name: string, fn: () => T): T;

Executes a function within a telemetry span.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | name | string | The span name | | fn | () => T | The function to execute within the span |

Returns

T

spanAsync()

spanAsync<T>(
   name: string, 
   fn: () => Promise<T>, 
config?: SpanConfig): Promise<T>;

Executes an async function within a telemetry span.

Type Parameters

| Type Parameter | | ------ | | T |

boolean

True if started, false otherwise

startedAsync()

startedAsync(notStartedAction?: "error" | "throw" | "warn" | "log" | "none", tryStart?: boolean): Promise<boolean>;

Async version of started that can optionally auto-start the instance.

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | notStartedAction | "error" | "throw" | "warn" | "log" | "none" | 'log' | What to do if not started and auto-start is disabled | | tryStart | boolean | true | If true, attempts to start the instance automatically |

Returns

Promise<boolean>

True if the instance is or becomes started

stop()

stop(): Promise<boolean>;

Stops the instance, transitioning through 'stopping' to 'stopped' status. Thread-safe via mutex. Returns true if already stopped or stopped successfully.

Returns

Promise<boolean>

_noOverride()

protected _noOverride(functionName?: string): void;

Asserts that the given function has not been overridden in a subclass. Used to enforce the handler pattern (override startHandler not start).

Parameters

| Parameter | Type | | ------ | ------ | | functionName | string |

Returns

void

setStatus()

Call Signature

protected setStatus(value: "creating" | "created" | "starting" | "started" | "stopping" | "stopped", progress?: number): void;

Sets the lifecycle status and reports it via the status reporter.

Parameters

| Parameter | Type | | ------ | ------ | | value | "creating" | "created" | "starting" | "started" | "stopping" | "stopped" | | progress? | number |

Returns

void

Call Signature

protected setStatus(value: "error", error?: Error): void;

Sets the lifecycle status and reports it via the status reporter.

this

This instance for chaining.

Inherited from

BaseEmitter.clearListeners

emit()

emit<TEventName, TEventArgs>(eventName: TEventName, eventArgs: TEventArgs): Promise<void>;

Emits an event, invoking all registered listeners concurrently.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventName extends string | number | symbol | keyof TEventData | | TEventArgs extends EventArgs | TEventData[TEventName] |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventArgs | The data to pass to listeners. |

Returns

Promise<void>

Inherited from

BaseEmitter.emit

emitSerial()

emitSerial<TEventName, TEventArgs>(eventName: TEventName, eventArgs: TEventArgs): Promise<void>;

Emits an event, invoking all registered listeners sequentially in order.

Type Parameters

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventArgs | The data to pass to listeners. |

Returns

Promise<void>

Inherited from

BaseEmitter.emitSerial

listenerCount()

listenerCount(eventNames: keyof TEventData | keyof TEventData[]): number;

Returns the total number of listeners registered for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] | One or more event names to count listeners for. |

Returns

number

The total listener count.

Inherited from

BaseEmitter.listenerCount

off()

off<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): void;

Removes a specific listener from the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | TEventName | TEventName[] | One or more event names to unsubscribe from. | | listener | EventListener<TEventData[TEventName]> | The listener to remove. |

Returns

void

Inherited from

BaseEmitter.off

offAny()

offAny(listener: EventAnyListener): void;

Removes a wildcard listener that was receiving all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The wildcard listener to remove. |

Returns

void

Inherited from

BaseEmitter.offAny

on()

on<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): () => void;

Subscribes a listener to the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | TEventName | TEventName[] | One or more event names to listen for. | | listener | EventListener<TEventData[TEventName]> | The callback to invoke when the event fires. |

Returns

An unsubscribe function.

(): void;

Returns

void

Inherited from

BaseEmitter.on

onAny()

onAny(listener: EventAnyListener): () => void;

Subscribes a wildcard listener that receives all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The callback to invoke for any event. |

Returns

An unsubscribe function.

(): void;

Returns

void

Inherited from

BaseEmitter.onAny

once()

once<TEventName>(eventName: TEventName, listener: EventListener<TEventData[TEventName]>): () => void;

Subscribes a listener that will be invoked only once for the specified event, then automatically removed.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to listen for. | | listener | EventListener<TEventData[TEventName]> | The callback to invoke once. |

Returns

An unsubscribe function.

(): void;

Returns

void

Inherited from

BaseEmitter.once

AbstractCreatableWithFactory

@xylabs/creatable

Extends AbstractCreatable with a static factory method for creating pre-configured CreatableFactory instances.

Extends

AbstractCreatable<TParams, TEventData>

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TParams extends CreatableParams | CreatableParams | | TEventData extends EventData | EventData |

Constructors

Constructor

new AbstractCreatableWithFactory<TParams, TEventData>(key: unknown, params: Partial<TParams & RequiredCreatableParams>): AbstractCreatableWithFactory<TParams, TEventData>;

Parameters

| Parameter | Type | | ------ | ------ | | key | unknown | | params | Partial<TParams & RequiredCreatableParams> |

Returns

AbstractCreatableWithFactory<TParams, TEventData>

Inherited from

AbstractCreatable.constructor

Properties

| Property | Modifier | Type | Description | Inherited from | | ------ | ------ | ------ | ------ | ------ | | defaultLogger? | static | Logger | - | AbstractCreatable.defaultLogger | | globalInstances | readonly | Record<BaseClassName, WeakRef<Base>[]> | - | AbstractCreatable.globalInstances | | globalInstancesCountHistory | readonly | Record<BaseClassName, number[]> | - | AbstractCreatable.globalInstancesCountHistory | | defaultLogger? | public | Logger | Optional default logger for this instance. | AbstractCreatable.defaultLogger | | _startPromise | protected | Promisable<boolean> | undefined | - | AbstractCreatable._startPromise | | eventData | public | TEventData | Type-level reference to the event data shape for external type queries. | AbstractCreatable.eventData |

Accessors

historyInterval

Get Signature

get static historyInterval(): number;

Returns

number

Set Signature

set static historyInterval(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

AbstractCreatable.historyInterval

historyTime

Get Signature

get static historyTime(): number;

Returns

number

Set Signature

set static historyTime(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

AbstractCreatable.historyTime

maxGcFrequency

Get Signature

get static maxGcFrequency(): number;

Returns

number

Set Signature

set static maxGcFrequency(value: number): void;

Get Signature

get name(): CreatableName;

The name identifier for this creatable instance.

Returns

CreatableName

Inherited from

AbstractCreatable.name

params

Get Signature

get params(): TParams & RequiredCreatableParams<void>;

The validated and merged parameters for this instance.

Returns

TParams & RequiredCreatableParams<void>

Inherited from

AbstractCreatable.params

startable

Get Signature

get startable(): boolean;

Whether this instance can be started (must be in 'created' or 'stopped' status).

Returns

boolean

Inherited from

AbstractCreatable.startable

status

Get Signature

get status(): CreatableStatus | null;

The current lifecycle status of this instance, or null if not yet initialized.

Returns

CreatableStatus | null

Inherited from

AbstractCreatable.status

statusReporter

Get Signature

get statusReporter(): 
  | CreatableStatusReporter<void>
  | undefined;

The status reporter used to broadcast lifecycle changes.

Returns

| CreatableStatusReporter<void> | undefined

Inherited from

AbstractCreatable.statusReporter

Methods

gc()

Call Signature

static gc(force?: boolean): void;

Asynchronously creates a new instance by processing params, constructing, and running both static and instance createHandlers.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | Creatable<T> | - | | inParams | Partial<T["params"]> | Optional partial parameters to configure the instance |

Returns

Promise<T>

The fully initialized instance

Inherited from

AbstractCreatable.create

createHandler()

static createHandler<T>(this: Creatable<T>, instance: T): Promisable<T>;

Static hook called during creation to perform additional initialization. Override in subclasses to customize post-construction setup.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | Creatable<T> | - | | instance | T | The newly constructed instance |

Returns

Promisable<T>

The instance, potentially modified

Inherited from

AbstractCreatable.createHandler

paramsHandler()

static paramsHandler<T>(this: Creatable<T>, params?: Partial<T["params"]>): Promisable<T["params"]>;

Static hook called during creation to validate and transform params. Override in subclasses to add default values or validation.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | Creatable<T> | - | | params | Partial<T["params"]> | The raw partial params provided to create |

Returns

Promisable<T["params"]>

The processed params ready for construction

Inherited from

AbstractCreatable.paramsHandler

createHandler()

createHandler(): Promisable<void>;

Instance-level creation hook. Override in subclasses to perform setup after construction.

Returns

Promisable<void>

Inherited from

AbstractCreatable.createHandler

paramsValidator()

paramsValidator(params: Partial<TParams & RequiredCreatableParams>): TParams & RequiredCreatableParams<void>;

Validates and returns the merged params, ensuring required fields are present. Override in subclasses to add custom validation logic.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | params | Partial<TParams & RequiredCreatableParams> | The raw partial params to validate |

Returns

TParams & RequiredCreatableParams<void>

The validated params

Inherited from

AbstractCreatable.paramsValidator

span()

span<T>(name: string, fn: () => T): T;

Executes a function within a telemetry span.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | name | string | The span name | | fn | () => T | The function to execute within the span |

Returns

T

Inherited from

AbstractCreatable.span

spanAsync()

spanAsync<T>(
   name: string, 
   fn: () => Promise<T>, 
config?: SpanConfig): Promise<T>;

Executes an async function within a telemetry span.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

Returns

Promise<T>

Inherited from

AbstractCreatable.spanAsync

start()

start(): Promise<boolean>;

Starts the instance, transitioning through 'starting' to 'started' status. Thread-safe via mutex. Returns true if already started or started successfully.

Returns

Promise<boolean>

Inherited from

AbstractCreatable.start

started()

started(notStartedAction?: "error" | "throw" | "warn" | "log" | "none"): boolean;

Checks whether this instance is currently started. Takes an action if not started, based on the notStartedAction parameter.

Parameters

Returns

boolean

True if started, false otherwise

Inherited from

AbstractCreatable.started

startedAsync()

startedAsync(notStartedAction?: "error" | "throw" | "warn" | "log" | "none", tryStart?: boolean): Promise<boolean>;

Async version of started that can optionally auto-start the instance.

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | notStartedAction | "error" | "throw" | "warn" | "log" | "none" | 'log' | What to do if not started and auto-start is disabled | | tryStart | boolean | true | If true, attempts to start the instance automatically |

Returns

Promise<boolean>

True if the instance is or becomes started

Inherited from

AbstractCreatable.startedAsync

stop()

stop(): Promise<boolean>;

Stops the instance, transitioning through 'stopping' to 'stopped' status. Thread-safe via mutex. Returns true if already stopped or stopped successfully.

Returns

Promise<boolean>

Inherited from

AbstractCreatable.stop

_noOverride()

protected _noOverride(functionName?: string): void;

Asserts that the given function has not been overridden in a subclass. Used to enforce the handler pattern (override startHandler not start).

Parameters

| Parameter | Type | | ------ | ------ | | functionName | string |

Returns

void

Inherited from

AbstractCreatable._noOverride

setStatus()

Call Signature

protected setStatus(value: "creating" | "created" | "starting" | "started" | "stopping" | "stopped", progress?: number): void;

Sets the lifecycle status and reports it via the status reporter.

Parameters

| Parameter | Type | | ------ | ------ | | value | "creating" | "created" | "starting" | "started" | "stopping" | "stopped" | | progress? | number |

Returns

void

Inherited from

AbstractCreatable.setStatus

Call Signature

protected setStatus(value: "error", error?: Error): void;

Sets the lifecycle status and reports it via the status reporter.

CreatableFactory<T>

clearListeners()

clearListeners(eventNames: keyof TEventData | keyof TEventData[]): this;

Removes all listeners for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] | One or more event names to clear listeners for. |

Returns

this

This instance for chaining.

Inherited from

AbstractCreatable.clearListeners

emit()

emit<TEventName, TEventArgs>(eventName: TEventName, eventArgs: TEventArgs): Promise<void>;

Emits an event, invoking all registered listeners concurrently.

Type Parameters

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventArgs | The data to pass to listeners. |

Returns

Promise<void>

Inherited from

AbstractCreatable.emit

emitSerial()

emitSerial<TEventName, TEventArgs>(eventName: TEventName, eventArgs: TEventArgs): Promise<void>;

Emits an event, invoking all registered listeners sequentially in order.

Type Parameters

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventArgs | The data to pass to listeners. |

Returns

Promise<void>

Inherited from

AbstractCreatable.emitSerial

listenerCount()

listenerCount(eventNames: keyof TEventData | keyof TEventData[]): number;

Returns the total number of listeners registered for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] | One or more event names to count listeners for. |

Returns

number

The total listener count.

Inherited from

AbstractCreatable.listenerCount

off()

off<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): void;

Removes a specific listener from the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

Returns

void

Inherited from

AbstractCreatable.off

offAny()

offAny(listener: EventAnyListener): void;

Removes a wildcard listener that was receiving all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The wildcard listener to remove. |

Returns

void

Inherited from

AbstractCreatable.offAny

on()

on<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): () => void;

Subscribes a listener to the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

Returns

An unsubscribe function.

(): void;

Returns

void

Inherited from

AbstractCreatable.on

onAny()

onAny(listener: EventAnyListener): () => void;

Subscribes a wildcard listener that receives all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The callback to invoke for any event. |

Returns

An unsubscribe function.

(): void;

Returns

void

Inherited from

AbstractCreatable.onAny

once()

once<TEventName>(eventName: TEventName, listener: EventListener<TEventData[TEventName]>): () => void;

Subscribes a listener that will be invoked only once for the specified event, then automatically removed.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

Returns

An unsubscribe function.

(): void;

Returns

void

Inherited from

AbstractCreatable.once

Factory

@xylabs/creatable

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.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T extends CreatableInstance | CreatableInstance |

Implements

CreatableFactory<T>

Constructors

Constructor

new Factory<T>(
   creatable: Creatable<T>, 
   params?: Partial<T["params"]>, 
labels?: Labels): Factory<T>;

Parameters

| Parameter | Type | | ------ | ------ | | creatable | Creatable<T> | | params? | Partial<T["params"]> | | labels? | Labels |

Returns

Factory<T>

Properties

| Property | Type | Description | | ------ | ------ | ------ | | creatable | Creatable<T> | The Creatable class this factory delegates creation to. | | defaultParams? | Partial<T["params"]> | Default parameters merged into every create call. | | labels? | Labels | Labels identifying resources created by this factory. |

Methods

withParams()

static withParams<T>(
   creatableModule: Creatable<T>, 
   params?: Partial<T["params"]>, 
labels?: Labels): Factory<T>;

Creates a new Factory instance with the given default params and labels.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | creatableModule | Creatable<T> | The Creatable class to wrap | | params? | Partial<T["params"]> | Default parameters for new instances | | labels? | Labels | Labels to assign to created instances |

Returns

Factory<T>

create()

create(params?: Partial<T["params"]>): Promise<T>;

Creates a new instance, merging the provided params over the factory defaults.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | params? | Partial<T["params"]> | Optional parameters to override the factory defaults |

Returns

Promise<T>

Implementation of

CreatableFactory.create

functions

creatable

@xylabs/creatable

function creatable<T>(): <U>(constructor: U) => void;

Class annotation to be used to decorate Modules which support an asynchronous creation pattern

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Returns

The decorated Module requiring it implement the members of the CreatableModule as statics properties/methods

<U>(constructor: U): void;

Type Parameters

| Type Parameter | | ------ | | U extends Creatable<T> |

Parameters

| Parameter | Type | | ------ | ------ | | constructor | U |

Returns

void

creatableFactory

@xylabs/creatable

function creatableFactory(): <U>(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

<U>(constructor: U): void;

Type Parameters

| Type Parameter | | ------ | | U extends CreatableFactory<CreatableInstance<CreatableParams, EventData>> |

Parameters

| Parameter | Type | | ------ | ------ | | constructor | U |

Returns

void

hasAllLabels

@xylabs/creatable

function hasAllLabels(source?: Labels, required?: Labels): boolean;

Returns true if the source object has all the labels from the required set

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | source? | Labels | Source object to check against | | required? | Labels | Set of labels to check for in source |

Returns

boolean

True of the source object has all the labels from the required set

interfaces

Creatable

@xylabs/creatable

Static interface for classes that support asynchronous creation. Provides the create, createHandler, and paramsHandler static methods used to construct instances through the creatable lifecycle.

Extended by

CreatableWithFactory

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T extends CreatableInstance | CreatableInstance |

Constructors

Constructor

new Creatable(key: unknown, params: Partial<CreatableParams>): T & AbstractCreatable<T["params"], EventData>;

Constructs a new raw instance. Should not be called directly; use create instead.

Parameters

| Parameter | Type | | ------ | ------ | | key | unknown | | params | Partial<CreatableParams> |

Returns

T & AbstractCreatable<T["params"], EventData>

Properties

| Property | Type | Description | | ------ | ------ | ------ | | defaultLogger? | Logger | Optional default logger shared across instances created by this class. |

Methods

create()

create<T>(this: Creatable<T>, params?: Partial<T["params"]>): Promise<T>;

Asynchronously creates and initializes a new instance with the given params.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | | ------ | ------ | | this | Creatable<T> | | params? | Partial<T["params"]> |

Returns

Promise<T>

createHandler()

createHandler<T>(this: Creatable<T>, instance: T): Promisable<T>;

Hook called after construction to perform additional initialization on the instance.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | | ------ | ------ | | this | Creatable<T> | | instance | T |

Returns

Promisable<T>

paramsHandler()

paramsHandler<T>(this: Creatable<T>, params?: Partial<T["params"]>): Promisable<T["params"] & RequiredCreatableParams<void>>;

Hook called to validate and transform params before instance construction.

Type Parameters

| Type Parameter | | ------ | | T extends CreatableInstance<CreatableParams, EventData> |

Parameters

| Parameter | Type | | ------ | ------ | | this | Creatable<T> | | params? | Partial<T["params"]> |

Returns

Promisable<T["params"] & RequiredCreatableParams<void>>

CreatableFactory

@xylabs/creatable

A factory interface for creating instances of a Creatable with pre-configured parameters. Unlike the full Creatable, this only exposes the create method.

Extends

Omit<Creatable<T>, | "create" | "createHandler" | "paramsHandler" | "defaultLogger" | "factory">

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T extends CreatableInstance | CreatableInstance |

Methods

create()

create(this: CreatableFactory<T>, params?: Partial<T["params"]>): Promise<T>;

Creates a new instance, merging the provided params with the factory's defaults.

Parameters

| Parameter | Type | | ------ | ------ | | this | CreatableFactory<T> | | params? | Partial<T["params"]> |

Returns

Promise<T>

CreatableInstance

@xylabs/creatable

Represents a created instance with a managed lifecycle (start/stop) and event emission.

Extends

EventEmitter<TEventData>

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TParams extends CreatableParams | CreatableParams | | TEventData extends EventData | EventData |

Properties

| Property | Type | Description | Overrides | | ------ | ------ | ------ | ------ | | eventData | TEventData | The event data type associated with this instance. | EventEmitter.eventData | | name | CreatableName | The name identifier for this instance. | - | | params | TParams | The parameters used to configure this instance. | - | | start | () => Promise<boolean> | Starts the instance. Resolves to true if started successfully. | - | | stop | () => Promise<boolean> | Stops the instance. Resolves to true if stopped successfully. | - |

Methods

clearListeners()

clearListeners(eventNames: keyof TEventData | keyof TEventData[]): void;

Removes all listeners for the specified event name(s).

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] |

Returns

void

Inherited from

EventEmitter.clearListeners

emit()

emit<TEventName>(eventName: TEventName, eventArgs: TEventData[TEventName]): Promise<void>;

Emits an event, invoking all registered listeners concurrently.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventName | TEventName | | eventArgs | TEventData[TEventName] |

Returns

Promise<void>

Inherited from

EventEmitter.emit

emitSerial()

emitSerial<TEventName>(eventName: TEventName, eventArgs: TEventData[TEventName]): Promise<void>;

Emits an event, invoking all registered listeners sequentially in order.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventName | TEventName | | eventArgs | TEventData[TEventName] |

Returns

Promise<void>

Inherited from

EventEmitter.emitSerial

listenerCount()

listenerCount(eventNames: keyof TEventData | keyof TEventData[]): number;

Returns the total number of listeners registered for the specified event name(s).

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] |

Returns

number

Inherited from

EventEmitter.listenerCount

off()

off<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): void;

Removes a specific listener from the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | TEventName | TEventName[] | | listener | EventListener<TEventData[TEventName]> |

Returns

void

Inherited from

EventEmitter.off

offAny()

offAny(listener: Promise<void> | EventAnyListener): void;

Removes a wildcard listener that was receiving all events.

Parameters

| Parameter | Type | | ------ | ------ | | listener | Promise<void> | EventAnyListener |

Returns

void

Inherited from

EventEmitter.offAny

on()

on<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): EventUnsubscribeFunction;

Subscribes a listener to the specified event name(s) and returns an unsubscribe function.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | TEventName | TEventName[] | | listener | EventListener<TEventData[TEventName]> |

Returns

EventUnsubscribeFunction

Inherited from

EventEmitter.on

onAny()

onAny(listener: EventAnyListener): EventUnsubscribeFunction;

Subscribes a wildcard listener that receives all events and returns an unsubscribe function.

Parameters

| Parameter | Type | | ------ | ------ | | listener | EventAnyListener |

Returns

EventUnsubscribeFunction

Inherited from

EventEmitter.onAny

once()

once<TEventName>(eventName: TEventName, listener: EventListener<TEventData[TEventName]>): EventUnsubscribeFunction;

Subscribes a listener that will be invoked only once for the specified event, then automatically removed.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventName | TEventName | | listener | EventListener<TEventData[TEventName]> |

Returns

EventUnsubscribeFunction

Inherited from

EventEmitter.once

CreatableParams

@xylabs/creatable

Parameters for creating a creatable instance, combining required params with emitter params.

Extends

RequiredCreatableParams.BaseEmitterParams

Properties

| Property | Type | Description | Inherited from | | ------ | ------ | ------ | ------ | | logger? | Logger | - | RequiredCreatableParams.logger | | meterProvider? | MeterProvider | - | RequiredCreatableParams.meterProvider | | traceProvider? | TracerProvider | - | RequiredCreatableParams.traceProvider | | name? | CreatableName | Optional name identifying this creatable instance. | RequiredCreatableParams.name | | statusReporter? | CreatableStatusReporter<void> | Optional reporter for broadcasting status changes. | RequiredCreatableParams.statusReporter |

CreatableStatusReporter

@xylabs/creatable

Reports status changes for a creatable, supporting progress tracking and error reporting.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TAdditionalStatus extends void | string | void |

Methods

report()

Call Signature

report(
   name: BaseClassName, 
   status: 
  | "creating"
  | "created"
  | "starting"
  | "started"
  | "stopping"
  | "stopped"
  | Exclude<TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus, "error">, 
   progress: number): void;

Report a non-error status with a numeric progress value.

Parameters

| Parameter | Type | | ------ | ------ | | name | BaseClassName | | status | | "creating" | "created" | "starting" | "started" | "stopping" | "stopped" | Exclude<TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus, "error"> | | progress | number |

Returns

void

Call Signature

report(
   name: BaseClassName, 
   status: 
  | "error"
  | Extract<TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus, "error">, 
   error: Error): void;

Report an error status with the associated Error.

Parameters

| Parameter | Type | | ------ | ------ | | name | BaseClassName | | status | | "error" | Extract<TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus, "error"> | | error | Error |

Returns

void

Call Signature

report(name: BaseClassName, status: CreatableStatus<TAdditionalStatus>): void;

Report a status change without progress or error details.

Parameters

| Parameter | Type | | ------ | ------ | | name | BaseClassName | | status | CreatableStatus<TAdditionalStatus> |

Returns

void

CreatableWithFactory

@xylabs/creatable

Extends Creatable with a factory method that produces pre-configured CreatableFactory instances.

Extends

Creatable<T>

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T extends CreatableInstance | CreatableInstance |

Constructors

Constructor

new CreatableWithFactory(key: unknown, params: Partial<CreatableParams>): T & AbstractCreatable<T["params"], EventData>;

Constructs a new raw instance. Should not be called directly; use create instead.

Parameters

| Parameter | Type | | ------ | ------ | | key | unknown | | params | Partial<CreatableParams> |

Returns

T & AbstractCreatable<T["params"], EventData>

Inherited from

Creatable.constructor

Properties

| Property | Type | Description | Inherited from | | ------ | ------ | ------ | ------ | | defaultLogger? | Logger | Optional default logger shared across instances created by this class. | Creatable.defaultLogger |

Methods

create()

create<T>(this: Creatable<T>, params?: Partial<T["params"]>): Promise<T>;

Asynchronously creates and initializes

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xylabs/creatable

Reference

Classes

Interfaces

Type Aliases

Functions

classes

AbstractCreatable

Extends

Extended by

Type Parameters

Constructors

Constructor

Parameters

Returns

Overrides

Properties

Accessors

historyInterval

Get Signature

Returns

Set Signature

Parameters

Returns

Inherited from

historyTime

Get Signature

Returns

Set Signature

Parameters

Returns

Inherited from

maxGcFrequency

Get Signature

Returns

Set Signature

Parameters

Returns

Inherited from

maxHistoryDepth

Get Signature

Returns

Inherited from

logger

Get Signature

Returns

Inherited from

meter

Get Signature

Returns

Inherited from

tracer

Get Signature

Returns

Inherited from

name

Get Signature

Returns

params

Get Signature

Returns

Overrides

startable

Get Signature

Returns

status

Get Signature

Returns

statusReporter

Get Signature

Returns

Methods

gc()

Call Signature