@xylabs/creatable
Advanced tools
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
### .temp-typedoc
### classes
### <a id="AbstractCreatable"></a>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.
BaseEmitter<Partial<TParams & RequiredCreatableParams>, TEventData>TParams extends CreatableParams = CreatableParams
TEventData extends EventData = EventData
new AbstractCreatable<TParams, TEventData>(key, params): AbstractCreatable<TParams, TEventData>;
unknown
Partial<TParams & RequiredCreatableParams>
AbstractCreatable<TParams, TEventData>
BaseEmitter<Partial<TParams & RequiredCreatableParams>, TEventData>.constructor
static optional defaultLogger?: Logger;
BaseEmitter.defaultLogger
readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]>;
BaseEmitter.globalInstances
readonly static globalInstancesCountHistory: Record<BaseClassName, number[]>;
BaseEmitter.globalInstancesCountHistory
optional defaultLogger?: Logger;
Optional default logger for this instance.
protected _startPromise: Promisable<boolean> | undefined;
eventData: TEventData;
Type-level reference to the event data shape for external type queries.
BaseEmitter.eventData
get static historyInterval(): number;
number
set static historyInterval(value): void;
number
void
BaseEmitter.historyInterval
get static historyTime(): number;
number
set static historyTime(value): void;
number
void
BaseEmitter.historyTime
get static maxGcFrequency(): number;
number
set static maxGcFrequency(value): void;
number
void
BaseEmitter.maxGcFrequency
get static maxHistoryDepth(): number;
number
BaseEmitter.maxHistoryDepth
get logger(): Logger | undefined;
Logger | undefined
BaseEmitter.logger
get meter(): Meter | undefined;
Meter | undefined
BaseEmitter.meter
get tracer(): Tracer | undefined;
Tracer | undefined
BaseEmitter.tracer
get name(): CreatableName;
The name identifier for this creatable instance.
get params(): TParams & RequiredCreatableParams<void>;
The validated and merged parameters for this instance.
TParams & RequiredCreatableParams<void>
BaseEmitter.params
get startable(): boolean;
Whether this instance can be started (must be in 'created' or 'stopped' status).
boolean
get status(): CreatableStatus | null;
The current lifecycle status of this instance, or null if not yet initialized.
CreatableStatus | null
get statusReporter():
| CreatableStatusReporter<void>
| undefined;
The status reporter used to broadcast lifecycle changes.
| CreatableStatusReporter<void>
| undefined
static gc(force?): void;
boolean
void
BaseEmitter.gc
static gc(className): void;
BaseClassName
void
BaseEmitter.gc
static instanceCount(className): number;
BaseClassName
number
BaseEmitter.instanceCount
static instanceCounts(): Record<BaseClassName, number>;
Record<BaseClassName, number>
BaseEmitter.instanceCounts
static startHistory(): void;
void
BaseEmitter.startHistory
static stopHistory(): void;
void
BaseEmitter.stopHistory
static create<T>(this, inParams?): Promise<T>;
Asynchronously creates a new instance by processing params, constructing, and running both static and instance createHandlers.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]> = {}
Optional partial parameters to configure the instance
Promise<T>
The fully initialized instance
static createHandler<T>(this, instance): Promisable<T>;
Static hook called during creation to perform additional initialization. Override in subclasses to customize post-construction setup.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
T
The newly constructed instance
Promisable<T>
The instance, potentially modified
static paramsHandler<T>(this, params?): Promisable<T["params"]>;
Static hook called during creation to validate and transform params. Override in subclasses to add default values or validation.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]> = {}
The raw partial params provided to create
Promisable<T["params"]>
The processed params ready for construction
createHandler(): Promisable<void>;
Instance-level creation hook. Override in subclasses to perform setup after construction.
Promisable<void>
paramsValidator(params): TParams & RequiredCreatableParams<void>;
Validates and returns the merged params, ensuring required fields are present. Override in subclasses to add custom validation logic.
Partial<TParams & RequiredCreatableParams>
The raw partial params to validate
TParams & RequiredCreatableParams<void>
The validated params
span<T>(name, fn): T;
Executes a function within a telemetry span.
T
string
The span name
() => T
The function to execute within the span
T
spanAsync<T>(
name,
fn,
config?): Promise<T>;
Executes an async function within a telemetry span.
T
string
The span name
() => Promise<T>
The async function to execute within the span
SpanConfig = {}
Optional span configuration
Promise<T>
start(): Promise<boolean>;
Starts the instance, transitioning through 'starting' to 'started' status. Thread-safe via mutex. Returns true if already started or started successfully.
Promise<boolean>
started(notStartedAction?): boolean;
Checks whether this instance is currently started. Takes an action if not started, based on the notStartedAction parameter.
"error" | "throw" | "warn" | "log" | "none"
What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
boolean
True if started, false otherwise
startedAsync(notStartedAction?, tryStart?): Promise<boolean>;
Async version of started that can optionally auto-start the instance.
"error" | "throw" | "warn" | "log" | "none"
What to do if not started and auto-start is disabled
boolean = true
If true, attempts to start the instance automatically
Promise<boolean>
True if the instance is or becomes started
stop(): Promise<boolean>;
Stops the instance, transitioning through 'stopping' to 'stopped' status. Thread-safe via mutex. Returns true if already stopped or stopped successfully.
Promise<boolean>
protected _noOverride(functionName?): void;
Asserts that the given function has not been overridden in a subclass.
Used to enforce the handler pattern (override startHandler not start).
string = ...
void
protected setStatus(value, progress?): void;
Sets the lifecycle status and reports it via the status reporter.
"creating" | "created" | "starting" | "started" | "stopping" | "stopped"
number
void
protected setStatus(value, error?): void;
Sets the lifecycle status and reports it via the status reporter.
"error"
Error
void
protected startHandler(): Promisable<void>;
Override in subclasses to define start behavior. Throw an error on failure.
Promisable<void>
protected stopHandler(): Promisable<void>;
Override in subclasses to define stop behavior. Throw an error on failure.
Promisable<void>
clearListeners(eventNames): this;
Removes all listeners for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to clear listeners for.
this
This instance for chaining.
BaseEmitter.clearListeners
emit<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners concurrently.
TEventName extends string | number | symbol = keyof TEventData
TEventArgs extends EventArgs = TEventData[TEventName]
TEventName
The event to emit.
TEventArgs
The data to pass to listeners.
Promise<void>
BaseEmitter.emit
emitSerial<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners sequentially in order.
TEventName extends string | number | symbol = keyof TEventData
TEventArgs extends EventArgs = TEventData[TEventName]
TEventName
The event to emit.
TEventArgs
The data to pass to listeners.
Promise<void>
BaseEmitter.emitSerial
listenerCount(eventNames): number;
Returns the total number of listeners registered for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to count listeners for.
number
The total listener count.
BaseEmitter.listenerCount
off<TEventName>(eventNames, listener): void;
Removes a specific listener from the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
One or more event names to unsubscribe from.
EventListener<TEventData[TEventName]>
The listener to remove.
void
BaseEmitter.off
offAny(listener): void;
Removes a wildcard listener that was receiving all events.
EventAnyListener
The wildcard listener to remove.
void
BaseEmitter.offAny
on<TEventName>(eventNames, listener): () => void;
Subscribes a listener to the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
One or more event names to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke when the event fires.
An unsubscribe function.
() => void
BaseEmitter.on
onAny(listener): () => void;
Subscribes a wildcard listener that receives all events.
EventAnyListener
The callback to invoke for any event.
An unsubscribe function.
() => void
BaseEmitter.onAny
once<TEventName>(eventName, listener): () => void;
Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
TEventName extends string | number | symbol
TEventName
The event to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke once.
An unsubscribe function.
() => void
BaseEmitter.once
### <a id="AbstractCreatableWithFactory"></a>AbstractCreatableWithFactory
Extends AbstractCreatable with a static factory method for creating
pre-configured CreatableFactory instances.
AbstractCreatable<TParams, TEventData>TParams extends CreatableParams = CreatableParams
TEventData extends EventData = EventData
new AbstractCreatableWithFactory<TParams, TEventData>(key, params): AbstractCreatableWithFactory<TParams, TEventData>;
unknown
Partial<TParams & RequiredCreatableParams>
AbstractCreatableWithFactory<TParams, TEventData>
static optional defaultLogger?: Logger;
AbstractCreatable.defaultLogger
readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]>;
AbstractCreatable.globalInstances
readonly static globalInstancesCountHistory: Record<BaseClassName, number[]>;
AbstractCreatable.globalInstancesCountHistory
optional defaultLogger?: Logger;
Optional default logger for this instance.
AbstractCreatable.defaultLogger
protected _startPromise: Promisable<boolean> | undefined;
AbstractCreatable._startPromise
eventData: TEventData;
Type-level reference to the event data shape for external type queries.
get static historyInterval(): number;
number
set static historyInterval(value): void;
number
void
AbstractCreatable.historyInterval
get static historyTime(): number;
number
set static historyTime(value): void;
number
void
get static maxGcFrequency(): number;
number
set static maxGcFrequency(value): void;
number
void
AbstractCreatable.maxGcFrequency
get static maxHistoryDepth(): number;
number
AbstractCreatable.maxHistoryDepth
get logger(): Logger | undefined;
Logger | undefined
get meter(): Meter | undefined;
Meter | undefined
get tracer(): Tracer | undefined;
Tracer | undefined
get name(): CreatableName;
The name identifier for this creatable instance.
get params(): TParams & RequiredCreatableParams<void>;
The validated and merged parameters for this instance.
TParams & RequiredCreatableParams<void>
get startable(): boolean;
Whether this instance can be started (must be in 'created' or 'stopped' status).
boolean
get status(): CreatableStatus | null;
The current lifecycle status of this instance, or null if not yet initialized.
CreatableStatus | null
get statusReporter():
| CreatableStatusReporter<void>
| undefined;
The status reporter used to broadcast lifecycle changes.
| CreatableStatusReporter<void>
| undefined
AbstractCreatable.statusReporter
static gc(force?): void;
boolean
void
static gc(className): void;
BaseClassName
void
static instanceCount(className): number;
BaseClassName
number
AbstractCreatable.instanceCount
static instanceCounts(): Record<BaseClassName, number>;
Record<BaseClassName, number>
AbstractCreatable.instanceCounts
static startHistory(): void;
void
AbstractCreatable.startHistory
static stopHistory(): void;
void
static create<T>(this, inParams?): Promise<T>;
Asynchronously creates a new instance by processing params, constructing, and running both static and instance createHandlers.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]> = {}
Optional partial parameters to configure the instance
Promise<T>
The fully initialized instance
static createHandler<T>(this, instance): Promisable<T>;
Static hook called during creation to perform additional initialization. Override in subclasses to customize post-construction setup.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
T
The newly constructed instance
Promisable<T>
The instance, potentially modified
AbstractCreatable.createHandler
static paramsHandler<T>(this, params?): Promisable<T["params"]>;
Static hook called during creation to validate and transform params. Override in subclasses to add default values or validation.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]> = {}
The raw partial params provided to create
Promisable<T["params"]>
The processed params ready for construction
AbstractCreatable.paramsHandler
createHandler(): Promisable<void>;
Instance-level creation hook. Override in subclasses to perform setup after construction.
Promisable<void>
AbstractCreatable.createHandler
paramsValidator(params): TParams & RequiredCreatableParams<void>;
Validates and returns the merged params, ensuring required fields are present. Override in subclasses to add custom validation logic.
Partial<TParams & RequiredCreatableParams>
The raw partial params to validate
TParams & RequiredCreatableParams<void>
The validated params
AbstractCreatable.paramsValidator
span<T>(name, fn): T;
Executes a function within a telemetry span.
T
string
The span name
() => T
The function to execute within the span
T
spanAsync<T>(
name,
fn,
config?): Promise<T>;
Executes an async function within a telemetry span.
T
string
The span name
() => Promise<T>
The async function to execute within the span
SpanConfig = {}
Optional span configuration
Promise<T>
start(): Promise<boolean>;
Starts the instance, transitioning through 'starting' to 'started' status. Thread-safe via mutex. Returns true if already started or started successfully.
Promise<boolean>
started(notStartedAction?): boolean;
Checks whether this instance is currently started. Takes an action if not started, based on the notStartedAction parameter.
"error" | "throw" | "warn" | "log" | "none"
What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
boolean
True if started, false otherwise
startedAsync(notStartedAction?, tryStart?): Promise<boolean>;
Async version of started that can optionally auto-start the instance.
"error" | "throw" | "warn" | "log" | "none"
What to do if not started and auto-start is disabled
boolean = true
If true, attempts to start the instance automatically
Promise<boolean>
True if the instance is or becomes started
AbstractCreatable.startedAsync
stop(): Promise<boolean>;
Stops the instance, transitioning through 'stopping' to 'stopped' status. Thread-safe via mutex. Returns true if already stopped or stopped successfully.
Promise<boolean>
protected _noOverride(functionName?): void;
Asserts that the given function has not been overridden in a subclass.
Used to enforce the handler pattern (override startHandler not start).
string = ...
void
protected setStatus(value, progress?): void;
Sets the lifecycle status and reports it via the status reporter.
"creating" | "created" | "starting" | "started" | "stopping" | "stopped"
number
void
protected setStatus(value, error?): void;
Sets the lifecycle status and reports it via the status reporter.
"error"
Error
void
protected startHandler(): Promisable<void>;
Override in subclasses to define start behavior. Throw an error on failure.
Promisable<void>
AbstractCreatable.startHandler
protected stopHandler(): Promisable<void>;
Override in subclasses to define stop behavior. Throw an error on failure.
Promisable<void>
static factory<T>(
this,
params?,
labels?): CreatableFactory<T>;
Creates a factory that produces instances of this class with pre-configured params and labels.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]>
Default parameters for instances created by the factory
Labels to assign to created instances
clearListeners(eventNames): this;
Removes all listeners for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to clear listeners for.
this
This instance for chaining.
AbstractCreatable.clearListeners
emit<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners concurrently.
TEventName extends string | number | symbol = keyof TEventData
TEventArgs extends EventArgs = TEventData[TEventName]
TEventName
The event to emit.
TEventArgs
The data to pass to listeners.
Promise<void>
emitSerial<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners sequentially in order.
TEventName extends string | number | symbol = keyof TEventData
TEventArgs extends EventArgs = TEventData[TEventName]
TEventName
The event to emit.
TEventArgs
The data to pass to listeners.
Promise<void>
listenerCount(eventNames): number;
Returns the total number of listeners registered for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to count listeners for.
number
The total listener count.
AbstractCreatable.listenerCount
off<TEventName>(eventNames, listener): void;
Removes a specific listener from the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
One or more event names to unsubscribe from.
EventListener<TEventData[TEventName]>
The listener to remove.
void
offAny(listener): void;
Removes a wildcard listener that was receiving all events.
EventAnyListener
The wildcard listener to remove.
void
on<TEventName>(eventNames, listener): () => void;
Subscribes a listener to the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
One or more event names to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke when the event fires.
An unsubscribe function.
() => void
onAny(listener): () => void;
Subscribes a wildcard listener that receives all events.
EventAnyListener
The callback to invoke for any event.
An unsubscribe function.
() => void
once<TEventName>(eventName, listener): () => void;
Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
TEventName extends string | number | symbol
TEventName
The event to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke once.
An unsubscribe function.
() => void
### <a id="Factory"></a>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.
T extends CreatableInstance = CreatableInstance
new Factory<T>(
creatable,
params?,
labels?): Factory<T>;
Creatable<T>
Partial<T["params"]>
Labels = {}
Factory<T>
creatable: Creatable<T>;
The Creatable class this factory delegates creation to.
optional defaultParams?: Partial<T["params"]>;
Default parameters merged into every create call.
optional labels?: Labels;
Labels identifying resources created by this factory.
static withParams<T>(
creatableModule,
params?,
labels?): Factory<T>;
Creates a new Factory instance with the given default params and labels.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
The Creatable class to wrap
Partial<T["params"]>
Default parameters for new instances
Labels = {}
Labels to assign to created instances
Factory<T>
create(params?): Promise<T>;
Creates a new instance, merging the provided params over the factory defaults.
Partial<T["params"]>
Optional parameters to override the factory defaults
Promise<T>
### functions
### <a id="creatable"></a>creatable
function creatable<T>(): <U>(constructor) => void;
Class annotation to be used to decorate Modules which support an asynchronous creation pattern
T extends CreatableInstance<CreatableParams, EventData>
The decorated Module requiring it implement the members of the CreatableModule as statics properties/methods
<U>(constructor) => void
### <a id="creatableFactory"></a>creatableFactory
function creatableFactory(): <U>(constructor) => void;
Class annotation to be used to decorate Modules which support an asynchronous creation factory pattern
The decorated Module requiring it implement the members of the CreatableModule as statics properties/methods
<U>(constructor) => void
### <a id="hasAllLabels"></a>hasAllLabels
function hasAllLabels(source?, required?): boolean;
Returns true if the source object has all the labels from the required set
Source object to check against
Set of labels to check for in source
boolean
True of the source object has all the labels from the required set
### interfaces
### <a id="Creatable"></a>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.
T extends CreatableInstance = CreatableInstance
new Creatable(key, params): T & AbstractCreatable<T["params"], EventData>;
Constructs a new raw instance. Should not be called directly; use create instead.
unknown
Partial<CreatableParams>
T & AbstractCreatable<T["params"], EventData>
optional defaultLogger?: Logger;
Optional default logger shared across instances created by this class.
create<T>(this, params?): Promise<T>;
Asynchronously creates and initializes a new instance with the given params.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]>
Promise<T>
createHandler<T>(this, instance): Promisable<T>;
Hook called after construction to perform additional initialization on the instance.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
T
Promisable<T>
paramsHandler<T>(this, params?): Promisable<T["params"] & RequiredCreatableParams<void>>;
Hook called to validate and transform params before instance construction.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]>
Promisable<T["params"] & RequiredCreatableParams<void>>
### <a id="CreatableFactory"></a>CreatableFactory
A factory interface for creating instances of a Creatable with pre-configured parameters.
Unlike the full Creatable, this only exposes the create method.
Omit<Creatable<T>,
| "create"
| "createHandler"
| "paramsHandler"
| "defaultLogger"
| "factory">T extends CreatableInstance = CreatableInstance
create(this, params?): Promise<T>;
Creates a new instance, merging the provided params with the factory's defaults.
CreatableFactory<T>
Partial<T["params"]>
Promise<T>
### <a id="CreatableInstance"></a>CreatableInstance
Represents a created instance with a managed lifecycle (start/stop) and event emission.
EventEmitter<TEventData>TParams extends CreatableParams = CreatableParams
TEventData extends EventData = EventData
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.
Promise<boolean>
stop: () => Promise<boolean>;
Stops the instance. Resolves to true if stopped successfully.
Promise<boolean>
clearListeners(eventNames): void;
Removes all listeners for the specified event name(s).
keyof TEventData | keyof TEventData[]
void
EventEmitter.clearListeners
emit<TEventName>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners concurrently.
TEventName extends string | number | symbol
TEventName
TEventData[TEventName]
Promise<void>
EventEmitter.emit
emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners sequentially in order.
TEventName extends string | number | symbol
TEventName
TEventData[TEventName]
Promise<void>
EventEmitter.emitSerial
listenerCount(eventNames): number;
Returns the total number of listeners registered for the specified event name(s).
keyof TEventData | keyof TEventData[]
number
EventEmitter.listenerCount
off<TEventName>(eventNames, listener): void;
Removes a specific listener from the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
EventListener<TEventData[TEventName]>
void
EventEmitter.off
offAny(listener): void;
Removes a wildcard listener that was receiving all events.
Promise<void> | EventAnyListener
void
EventEmitter.offAny
on<TEventName>(eventNames, listener): EventUnsubscribeFunction;
Subscribes a listener to the specified event name(s) and returns an unsubscribe function.
TEventName extends string | number | symbol
TEventName | TEventName[]
EventListener<TEventData[TEventName]>
EventUnsubscribeFunction
EventEmitter.on
onAny(listener): EventUnsubscribeFunction;
Subscribes a wildcard listener that receives all events and returns an unsubscribe function.
EventAnyListener
EventUnsubscribeFunction
EventEmitter.onAny
once<TEventName>(eventName, listener): EventUnsubscribeFunction;
Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
TEventName extends string | number | symbol
TEventName
EventListener<TEventData[TEventName]>
EventUnsubscribeFunction
EventEmitter.once
### <a id="CreatableParams"></a>CreatableParams
Parameters for creating a creatable instance, combining required params with emitter params.
RequiredCreatableParams.BaseEmitterParamsoptional logger?: Logger;
RequiredCreatableParams.logger
optional meterProvider?: MeterProvider;
RequiredCreatableParams.meterProvider
optional traceProvider?: TracerProvider;
RequiredCreatableParams.traceProvider
optional name?: CreatableName;
Optional name identifying this creatable instance.
optional statusReporter?: CreatableStatusReporter<void>;
Optional reporter for broadcasting status changes.
RequiredCreatableParams.statusReporter
### <a id="CreatableStatusReporter"></a>CreatableStatusReporter
Reports status changes for a creatable, supporting progress tracking and error reporting.
TAdditionalStatus extends void | string = void
report(
name,
status,
progress): void;
Report a non-error status with a numeric progress value.
BaseClassName
| "creating"
| "created"
| "starting"
| "started"
| "stopping"
| "stopped"
| Exclude<TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus, "error">
number
void
report(
name,
status,
error): void;
Report an error status with the associated Error.
BaseClassName
| "error"
| Extract<TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus, "error">
Error
void
report(name, status): void;
Report a status change without progress or error details.
BaseClassName
CreatableStatus<TAdditionalStatus>
void
### <a id="CreatableWithFactory"></a>CreatableWithFactory
Extends Creatable with a factory method that produces pre-configured CreatableFactory instances.
Creatable<T>T extends CreatableInstance = CreatableInstance
new CreatableWithFactory(key, params): T & AbstractCreatable<T["params"], EventData>;
Constructs a new raw instance. Should not be called directly; use create instead.
unknown
Partial<CreatableParams>
T & AbstractCreatable<T["params"], EventData>
optional defaultLogger?: Logger;
Optional default logger shared across instances created by this class.
create<T>(this, params?): Promise<T>;
Asynchronously creates and initializes a new instance with the given params.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]>
Promise<T>
createHandler<T>(this, instance): Promisable<T>;
Hook called after construction to perform additional initialization on the instance.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
T
Promisable<T>
paramsHandler<T>(this, params?): Promisable<T["params"] & RequiredCreatableParams<void>>;
Hook called to validate and transform params before instance construction.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]>
Promisable<T["params"] & RequiredCreatableParams<void>>
factory<T>(
this,
params?,
labels?): CreatableFactory<T>;
Creates a factory with the given default params and labels.
T extends CreatableInstance<CreatableParams, EventData>
Creatable<T>
Partial<T["params"]>
### <a id="RequiredCreatableParams"></a>RequiredCreatableParams
The minimum required parameters for constructing a creatable.
BaseEmitterParamsTAdditionalStatus extends CreatableStatus | void = void
optional logger?: Logger;
BaseEmitterParams.logger
optional meterProvider?: MeterProvider;
BaseEmitterParams.meterProvider
optional traceProvider?: TracerProvider;
BaseEmitterParams.traceProvider
optional name?: CreatableName;
Optional name identifying this creatable instance.
optional statusReporter?: CreatableStatusReporter<TAdditionalStatus>;
Optional reporter for broadcasting status changes.
### <a id="WithLabels"></a>WithLabels
Interface for objects that have labels.
labels: T;
### <a id="WithOptionalLabels"></a>WithOptionalLabels
Interface for objects that have labels.
optional labels?: T;
### type-aliases
### <a id="CreatableName"></a>CreatableName
type CreatableName = Exclude<string, "creatable-name-reserved-32546239486"> & BaseClassName;
A branded string type used as the name identifier for creatables.
### <a id="CreatableStatus"></a>CreatableStatus
type CreatableStatus<TAdditionalStatus> =
| StandardCreatableStatus
| TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus;
A creatable's status, optionally extended with additional custom status values.
TAdditionalStatus extends void | string = void
### <a id="Labels"></a>Labels
type Labels = Record<string, string | undefined>;
Object used to represent labels identifying a resource.
### <a id="StandardCreatableStatus"></a>StandardCreatableStatus
type StandardCreatableStatus =
| "creating"
| "created"
| "starting"
| "started"
| "stopping"
| "stopped"
| "error";
The standard lifecycle statuses a creatable can transition through.
FAQs
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
The npm package @xylabs/creatable receives a total of 3,354 weekly downloads. As such, @xylabs/creatable popularity was classified as popular.
We found that @xylabs/creatable demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Bitwarden CLI 2026.4.0 was compromised in the Checkmarx supply chain campaign after attackers abused a GitHub Action in Bitwarden’s CI/CD pipeline.
Research
/Security News
Docker and Socket have uncovered malicious Checkmarx KICS images and suspicious code extension releases in a broader supply chain compromise.
Product
Stay on top of alert changes with filtered subscriptions, batched summaries, and notification routing built for triage.