@xylabs/creatable 5.0.80 → 5.0.82

package/README.md

@@ -33,6 +33,7 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 - [Creatable](#interfaces/Creatable)
 - [CreatableWithFactory](#interfaces/CreatableWithFactory)
 - [CreatableInstance](#interfaces/CreatableInstance)
+- [RequiredCreatableParams](#interfaces/RequiredCreatableParams)
 - [CreatableParams](#interfaces/CreatableParams)
 - [CreatableStatusReporter](#interfaces/CreatableStatusReporter)
 - [Labels](#interfaces/Labels)
@@ -42,6 +43,7 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 ## Type Aliases
 
 - [CreatableName](#type-aliases/CreatableName)
+- [StandardCreatableStatus](#type-aliases/StandardCreatableStatus)
 - [CreatableStatus](#type-aliases/CreatableStatus)
 
 ## Functions
@@ -58,9 +60,13 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+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`\>, `TEventData`\>
+- `BaseEmitter`\<`Partial`\<`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\>, `TEventData`\>
 
 ## Extended by
 
@@ -92,7 +98,7 @@ new AbstractCreatable<TParams, TEventData>(key, params): AbstractCreatable<TPara
 
 #### params
 
-`Partial`\<`TParams`\>
+`Partial`\<`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\>
 
 ### Returns
 
@@ -101,7 +107,7 @@ new AbstractCreatable<TParams, TEventData>(key, params): AbstractCreatable<TPara
 ### Overrides
 
 ```ts
-BaseEmitter<Partial<TParams>, TEventData>.constructor
+BaseEmitter<Partial<TParams & RequiredCreatableParams>, TEventData>.constructor
 ```
 
 ## Properties
@@ -148,24 +154,20 @@ BaseEmitter.globalInstancesCountHistory
 
 ***
 
-### uniqueName
+### defaultLogger?
 
 ```ts
-readonly static uniqueName: string;
+optional defaultLogger: Logger;
 ```
 
-### Inherited from
-
-```ts
-BaseEmitter.uniqueName
-```
+Optional default logger for this instance.
 
 ***
 
-### defaultLogger?
+### \_startPromise
 
 ```ts
-optional defaultLogger: Logger;
+protected _startPromise: Promisable<boolean> | undefined;
 ```
 
 ***
@@ -317,12 +319,12 @@ BaseEmitter.maxHistoryDepth
 ### Get Signature
 
 ```ts
-get logger(): undefined | Logger;
+get logger(): Logger | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Logger`
+`Logger` \| `undefined`
 
 ### Inherited from
 
@@ -337,12 +339,12 @@ BaseEmitter.logger
 ### Get Signature
 
 ```ts
-get meter(): undefined | Meter;
+get meter(): Meter | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Meter`
+`Meter` \| `undefined`
 
 ### Inherited from
 
@@ -357,12 +359,12 @@ BaseEmitter.meter
 ### Get Signature
 
 ```ts
-get tracer(): undefined | Tracer;
+get tracer(): Tracer | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Tracer`
+`Tracer` \| `undefined`
 
 ### Inherited from
 
@@ -377,12 +379,14 @@ BaseEmitter.tracer
 ### Get Signature
 
 ```ts
-get name(): string;
+get name(): CreatableName;
 ```
 
+The name identifier for this creatable instance.
+
 #### Returns
 
-`string`
+[`CreatableName`](#../type-aliases/CreatableName)
 
 ***
 
@@ -391,12 +395,14 @@ get name(): string;
 ### Get Signature
 
 ```ts
-get params(): TParams;
+get params(): TParams & RequiredCreatableParams<void>;
 ```
 
+The validated and merged parameters for this instance.
+
 #### Returns
 
-`TParams`
+`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\<`void`\>
 
 ### Overrides
 
@@ -406,20 +412,54 @@ BaseEmitter.params
 
 ***
 
+### startable
+
+### Get Signature
+
+```ts
+get startable(): boolean;
+```
+
+Whether this instance can be started (must be in 'created' or 'stopped' status).
+
+#### Returns
+
+`boolean`
+
+***
+
+### status
+
+### Get Signature
+
+```ts
+get status(): CreatableStatus | null;
+```
+
+The current lifecycle status of this instance, or null if not yet initialized.
+
+#### Returns
+
+[`CreatableStatus`](#../type-aliases/CreatableStatus) \| `null`
+
+***
+
 ### statusReporter
 
 ### Get Signature
 
 ```ts
 get statusReporter(): 
-  | undefined
-| CreatableStatusReporter<void>;
+  | CreatableStatusReporter<void>
+  | undefined;
 ```
 
+The status reporter used to broadcast lifecycle changes.
+
 #### Returns
 
-  \| `undefined`
   \| [`CreatableStatusReporter`](#../interfaces/CreatableStatusReporter)\<`void`\>
+  \| `undefined`
 
 ## Methods
 
@@ -457,7 +497,7 @@ static gc(className): void;
 
 ##### className
 
-`string`
+`BaseClassName`
 
 #### Returns
 
@@ -481,7 +521,7 @@ static instanceCount(className): number;
 
 #### className
 
-`string`
+`BaseClassName`
 
 ### Returns
 
@@ -552,9 +592,12 @@ BaseEmitter.stopHistory
 ### create()
 
 ```ts
-static create<T>(this, inParams): Promise<T>;
+static create<T>(this, inParams?): Promise<T>;
 ```
 
+Asynchronously creates a new instance by processing params, constructing,
+and running both static and instance createHandlers.
+
 ### Type Parameters
 
 #### T
@@ -567,14 +610,18 @@ static create<T>(this, inParams): Promise<T>;
 
 [`Creatable`](#../interfaces/Creatable)\<`T`\>
 
-#### inParams
+#### inParams?
 
 `Partial`\<`T`\[`"params"`\]\> = `{}`
 
+Optional partial parameters to configure the instance
+
 ### Returns
 
 `Promise`\<`T`\>
 
+The fully initialized instance
+
 ***
 
 ### createHandler()
@@ -583,6 +630,9 @@ static create<T>(this, inParams): Promise<T>;
 static createHandler<T>(this, instance): Promisable<T>;
 ```
 
+Static hook called during creation to perform additional initialization.
+Override in subclasses to customize post-construction setup.
+
 ### Type Parameters
 
 #### T
@@ -599,18 +649,25 @@ static createHandler<T>(this, instance): Promisable<T>;
 
 `T`
 
+The newly constructed instance
+
 ### Returns
 
 `Promisable`\<`T`\>
 
+The instance, potentially modified
+
 ***
 
 ### paramsHandler()
 
 ```ts
-static paramsHandler<T>(this, params): Promisable<T["params"]>;
+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.
+
 ### Type Parameters
 
 #### T
@@ -623,14 +680,18 @@ static paramsHandler<T>(this, params): Promisable<T["params"]>;
 
 [`Creatable`](#../interfaces/Creatable)\<`T`\>
 
-#### params
+#### params?
 
 `Partial`\<`T`\[`"params"`\]\> = `{}`
 
+The raw partial params provided to `create`
+
 ### Returns
 
 `Promisable`\<`T`\[`"params"`\]\>
 
+The processed params ready for construction
+
 ***
 
 ### createHandler()
@@ -639,6 +700,8 @@ static paramsHandler<T>(this, params): Promisable<T["params"]>;
 createHandler(): Promisable<void>;
 ```
 
+Instance-level creation hook. Override in subclasses to perform setup after construction.
+
 ### Returns
 
 `Promisable`\<`void`\>
@@ -648,18 +711,102 @@ createHandler(): Promisable<void>;
 ### paramsValidator()
 
 ```ts
-paramsValidator(params): TParams;
+paramsValidator(params): TParams & RequiredCreatableParams<void>;
 ```
 
+Validates and returns the merged params, ensuring required fields are present.
+Override in subclasses to add custom validation logic.
+
 ### Parameters
 
 #### params
 
-`Partial`\<`TParams`\>
+`Partial`\<`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\>
+
+The raw partial params to validate
+
+### Returns
+
+`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\<`void`\>
+
+The validated params
+
+***
+
+### span()
+
+```ts
+span<T>(name, fn): T;
+```
+
+Executes a function within a telemetry span.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### name
+
+`string`
+
+The span name
+
+#### fn
+
+() => `T`
+
+The function to execute within the span
+
+### Returns
+
+`T`
+
+***
+
+### spanAsync()
+
+```ts
+spanAsync<T>(
+   name, 
+   fn, 
+config?): Promise<T>;
+```
+
+Executes an async function within a telemetry span.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### name
+
+`string`
+
+The span name
+
+#### fn
+
+() => `Promise`\<`T`\>
+
+The async function to execute within the span
+
+#### config?
+
+`SpanConfig` = `{}`
+
+Optional span configuration
 
 ### Returns
 
-`TParams`
+`Promise`\<`T`\>
 
 ***
 
@@ -669,10 +816,68 @@ paramsValidator(params): TParams;
 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`\>
+
+***
+
+### started()
+
+```ts
+started(notStartedAction?): boolean;
+```
+
+Checks whether this instance is currently started.
+Takes an action if not started, based on the notStartedAction parameter.
+
+### Parameters
+
+#### notStartedAction?
+
+What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
+
+`"error"` | `"throw"` | `"warn"` | `"log"` | `"none"`
+
+### Returns
+
+`boolean`
+
+True if started, false otherwise
+
+***
+
+### startedAsync()
+
+```ts
+startedAsync(notStartedAction?, tryStart?): Promise<boolean>;
+```
+
+Async version of `started` that can optionally auto-start the instance.
+
+### Parameters
+
+#### notStartedAction?
+
+What to do if not started and auto-start is disabled
+
+`"error"` | `"throw"` | `"warn"` | `"log"` | `"none"`
+
+#### tryStart?
+
+`boolean` = `true`
+
+If true, attempts to start the instance automatically
+
 ### Returns
 
 `Promise`\<`boolean`\>
 
+True if the instance is or becomes started
+
 ***
 
 ### stop()
@@ -681,6 +886,9 @@ start(): Promise<boolean>;
 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`\>
@@ -690,12 +898,15 @@ stop(): Promise<boolean>;
 ### \_noOverride()
 
 ```ts
-protected _noOverride(functionName): void;
+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`).
+
 ### Parameters
 
-#### functionName
+#### functionName?
 
 `string` = `...`
 
@@ -705,12 +916,62 @@ protected _noOverride(functionName): void;
 
 ***
 
+### setStatus()
+
+### Call Signature
+
+```ts
+protected setStatus(value, progress?): void;
+```
+
+Sets the lifecycle status and reports it via the status reporter.
+
+#### Parameters
+
+##### value
+
+`"creating"` | `"created"` | `"starting"` | `"started"` | `"stopping"` | `"stopped"`
+
+##### progress?
+
+`number`
+
+#### Returns
+
+`void`
+
+### Call Signature
+
+```ts
+protected setStatus(value, error?): void;
+```
+
+Sets the lifecycle status and reports it via the status reporter.
+
+#### Parameters
+
+##### value
+
+`"error"`
+
+##### error?
+
+`Error`
+
+#### Returns
+
+`void`
+
+***
+
 ### startHandler()
 
 ```ts
 protected startHandler(): Promisable<void>;
 ```
 
+Override in subclasses to define start behavior. Throw an error on failure.
+
 ### Returns
 
 `Promisable`\<`void`\>
@@ -723,6 +984,8 @@ protected startHandler(): Promisable<void>;
 protected stopHandler(): Promisable<void>;
 ```
 
+Override in subclasses to define stop behavior. Throw an error on failure.
+
 ### Returns
 
 `Promisable`\<`void`\>
@@ -1025,6 +1288,9 @@ BaseEmitter.once
 
 ***
 
+Extends AbstractCreatable with a static `factory` method for creating
+pre-configured CreatableFactory instances.
+
 ## Extends
 
 - [`AbstractCreatable`](#AbstractCreatable)\<`TParams`, `TEventData`\>
@@ -1055,7 +1321,7 @@ new AbstractCreatableWithFactory<TParams, TEventData>(key, params): AbstractCrea
 
 #### params
 
-`Partial`\<`TParams`\>
+`Partial`\<`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\>
 
 ### Returns
 
@@ -1103,27 +1369,29 @@ readonly static globalInstancesCountHistory: Record<BaseClassName, number[]>;
 
 ***
 
-### uniqueName
+### defaultLogger?
 
 ```ts
-readonly static uniqueName: string;
+optional defaultLogger: Logger;
 ```
 
+Optional default logger for this instance.
+
 ### Inherited from
 
-[`AbstractCreatable`](#AbstractCreatable).[`uniqueName`](AbstractCreatable.md#uniquename)
+[`AbstractCreatable`](#AbstractCreatable).[`defaultLogger`](AbstractCreatable.md#defaultlogger-1)
 
 ***
 
-### defaultLogger?
+### \_startPromise
 
 ```ts
-optional defaultLogger: Logger;
+protected _startPromise: Promisable<boolean> | undefined;
 ```
 
 ### Inherited from
 
-[`AbstractCreatable`](#AbstractCreatable).[`defaultLogger`](AbstractCreatable.md#defaultlogger-1)
+[`AbstractCreatable`](#AbstractCreatable).[`_startPromise`](AbstractCreatable.md#_startpromise)
 
 ***
 
@@ -1264,12 +1532,12 @@ get static maxHistoryDepth(): number;
 ### Get Signature
 
 ```ts
-get logger(): undefined | Logger;
+get logger(): Logger | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Logger`
+`Logger` \| `undefined`
 
 ### Inherited from
 
@@ -1282,12 +1550,12 @@ get logger(): undefined | Logger;
 ### Get Signature
 
 ```ts
-get meter(): undefined | Meter;
+get meter(): Meter | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Meter`
+`Meter` \| `undefined`
 
 ### Inherited from
 
@@ -1300,12 +1568,12 @@ get meter(): undefined | Meter;
 ### Get Signature
 
 ```ts
-get tracer(): undefined | Tracer;
+get tracer(): Tracer | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Tracer`
+`Tracer` \| `undefined`
 
 ### Inherited from
 
@@ -1318,12 +1586,14 @@ get tracer(): undefined | Tracer;
 ### Get Signature
 
 ```ts
-get name(): string;
+get name(): CreatableName;
 ```
 
+The name identifier for this creatable instance.
+
 #### Returns
 
-`string`
+[`CreatableName`](#../type-aliases/CreatableName)
 
 ### Inherited from
 
@@ -1336,12 +1606,14 @@ get name(): string;
 ### Get Signature
 
 ```ts
-get params(): TParams;
+get params(): TParams & RequiredCreatableParams<void>;
 ```
 
+The validated and merged parameters for this instance.
+
 #### Returns
 
-`TParams`
+`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\<`void`\>
 
 ### Inherited from
 
@@ -1349,20 +1621,62 @@ get params(): TParams;
 
 ***
 
+### startable
+
+### Get Signature
+
+```ts
+get startable(): boolean;
+```
+
+Whether this instance can be started (must be in 'created' or 'stopped' status).
+
+#### Returns
+
+`boolean`
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`startable`](AbstractCreatable.md#startable)
+
+***
+
+### status
+
+### Get Signature
+
+```ts
+get status(): CreatableStatus | null;
+```
+
+The current lifecycle status of this instance, or null if not yet initialized.
+
+#### Returns
+
+[`CreatableStatus`](#../type-aliases/CreatableStatus) \| `null`
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`status`](AbstractCreatable.md#status)
+
+***
+
 ### statusReporter
 
 ### Get Signature
 
 ```ts
 get statusReporter(): 
-  | undefined
-| CreatableStatusReporter<void>;
+  | CreatableStatusReporter<void>
+  | undefined;
 ```
 
+The status reporter used to broadcast lifecycle changes.
+
 #### Returns
 
-  \| `undefined`
   \| [`CreatableStatusReporter`](#../interfaces/CreatableStatusReporter)\<`void`\>
+  \| `undefined`
 
 ### Inherited from
 
@@ -1402,7 +1716,7 @@ static gc(className): void;
 
 ##### className
 
-`string`
+`BaseClassName`
 
 #### Returns
 
@@ -1424,7 +1738,7 @@ static instanceCount(className): number;
 
 #### className
 
-`string`
+`BaseClassName`
 
 ### Returns
 
@@ -1487,9 +1801,12 @@ static stopHistory(): void;
 ### create()
 
 ```ts
-static create<T>(this, inParams): Promise<T>;
+static create<T>(this, inParams?): Promise<T>;
 ```
 
+Asynchronously creates a new instance by processing params, constructing,
+and running both static and instance createHandlers.
+
 ### Type Parameters
 
 #### T
@@ -1502,14 +1819,18 @@ static create<T>(this, inParams): Promise<T>;
 
 [`Creatable`](#../interfaces/Creatable)\<`T`\>
 
-#### inParams
+#### inParams?
 
 `Partial`\<`T`\[`"params"`\]\> = `{}`
 
+Optional partial parameters to configure the instance
+
 ### Returns
 
 `Promise`\<`T`\>
 
+The fully initialized instance
+
 ### Inherited from
 
 [`AbstractCreatable`](#AbstractCreatable).[`create`](AbstractCreatable.md#create)
@@ -1522,6 +1843,9 @@ static create<T>(this, inParams): Promise<T>;
 static createHandler<T>(this, instance): Promisable<T>;
 ```
 
+Static hook called during creation to perform additional initialization.
+Override in subclasses to customize post-construction setup.
+
 ### Type Parameters
 
 #### T
@@ -1538,10 +1862,14 @@ static createHandler<T>(this, instance): Promisable<T>;
 
 `T`
 
+The newly constructed instance
+
 ### Returns
 
 `Promisable`\<`T`\>
 
+The instance, potentially modified
+
 ### Inherited from
 
 [`AbstractCreatable`](#AbstractCreatable).[`createHandler`](AbstractCreatable.md#createhandler)
@@ -1551,9 +1879,12 @@ static createHandler<T>(this, instance): Promisable<T>;
 ### paramsHandler()
 
 ```ts
-static paramsHandler<T>(this, params): Promisable<T["params"]>;
+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.
+
 ### Type Parameters
 
 #### T
@@ -1566,109 +1897,335 @@ static paramsHandler<T>(this, params): Promisable<T["params"]>;
 
 [`Creatable`](#../interfaces/Creatable)\<`T`\>
 
-#### params
+#### params?
 
 `Partial`\<`T`\[`"params"`\]\> = `{}`
 
+The raw partial params provided to `create`
+
+### Returns
+
+`Promisable`\<`T`\[`"params"`\]\>
+
+The processed params ready for construction
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`paramsHandler`](AbstractCreatable.md#paramshandler)
+
+***
+
+### createHandler()
+
+```ts
+createHandler(): Promisable<void>;
+```
+
+Instance-level creation hook. Override in subclasses to perform setup after construction.
+
+### Returns
+
+`Promisable`\<`void`\>
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`createHandler`](AbstractCreatable.md#createhandler-1)
+
+***
+
+### paramsValidator()
+
+```ts
+paramsValidator(params): TParams & RequiredCreatableParams<void>;
+```
+
+Validates and returns the merged params, ensuring required fields are present.
+Override in subclasses to add custom validation logic.
+
+### Parameters
+
+#### params
+
+`Partial`\<`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\>
+
+The raw partial params to validate
+
+### Returns
+
+`TParams` & [`RequiredCreatableParams`](#../interfaces/RequiredCreatableParams)\<`void`\>
+
+The validated params
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`paramsValidator`](AbstractCreatable.md#paramsvalidator)
+
+***
+
+### span()
+
+```ts
+span<T>(name, fn): T;
+```
+
+Executes a function within a telemetry span.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### name
+
+`string`
+
+The span name
+
+#### fn
+
+() => `T`
+
+The function to execute within the span
+
+### Returns
+
+`T`
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`span`](AbstractCreatable.md#span)
+
+***
+
+### spanAsync()
+
+```ts
+spanAsync<T>(
+   name, 
+   fn, 
+config?): Promise<T>;
+```
+
+Executes an async function within a telemetry span.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### name
+
+`string`
+
+The span name
+
+#### fn
+
+() => `Promise`\<`T`\>
+
+The async function to execute within the span
+
+#### config?
+
+`SpanConfig` = `{}`
+
+Optional span configuration
+
+### Returns
+
+`Promise`\<`T`\>
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`spanAsync`](AbstractCreatable.md#spanasync)
+
+***
+
+### start()
+
+```ts
+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`](#AbstractCreatable).[`start`](AbstractCreatable.md#start)
+
+***
+
+### started()
+
+```ts
+started(notStartedAction?): boolean;
+```
+
+Checks whether this instance is currently started.
+Takes an action if not started, based on the notStartedAction parameter.
+
+### Parameters
+
+#### notStartedAction?
+
+What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
+
+`"error"` | `"throw"` | `"warn"` | `"log"` | `"none"`
+
+### Returns
+
+`boolean`
+
+True if started, false otherwise
+
+### Inherited from
+
+[`AbstractCreatable`](#AbstractCreatable).[`started`](AbstractCreatable.md#started)
+
+***
+
+### startedAsync()
+
+```ts
+startedAsync(notStartedAction?, tryStart?): Promise<boolean>;
+```
+
+Async version of `started` that can optionally auto-start the instance.
+
+### Parameters
+
+#### notStartedAction?
+
+What to do if not started and auto-start is disabled
+
+`"error"` | `"throw"` | `"warn"` | `"log"` | `"none"`
+
+#### tryStart?
+
+`boolean` = `true`
+
+If true, attempts to start the instance automatically
+
 ### Returns
 
-`Promisable`\<`T`\[`"params"`\]\>
+`Promise`\<`boolean`\>
+
+True if the instance is or becomes started
 
 ### Inherited from
 
-[`AbstractCreatable`](#AbstractCreatable).[`paramsHandler`](AbstractCreatable.md#paramshandler)
+[`AbstractCreatable`](#AbstractCreatable).[`startedAsync`](AbstractCreatable.md#startedasync)
 
 ***
 
-### createHandler()
+### stop()
 
 ```ts
-createHandler(): Promisable<void>;
+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
 
-`Promisable`\<`void`\>
+`Promise`\<`boolean`\>
 
 ### Inherited from
 
-[`AbstractCreatable`](#AbstractCreatable).[`createHandler`](AbstractCreatable.md#createhandler-2)
+[`AbstractCreatable`](#AbstractCreatable).[`stop`](AbstractCreatable.md#stop)
 
 ***
 
-### paramsValidator()
+### \_noOverride()
 
 ```ts
-paramsValidator(params): TParams;
+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`).
+
 ### Parameters
 
-#### params
+#### functionName?
 
-`Partial`\<`TParams`\>
+`string` = `...`
 
 ### Returns
 
-`TParams`
+`void`
 
 ### Inherited from
 
-[`AbstractCreatable`](#AbstractCreatable).[`paramsValidator`](AbstractCreatable.md#paramsvalidator)
+[`AbstractCreatable`](#AbstractCreatable).[`_noOverride`](AbstractCreatable.md#_nooverride)
 
 ***
 
-### start()
+### setStatus()
+
+### Call Signature
 
 ```ts
-start(): Promise<boolean>;
+protected setStatus(value, progress?): void;
 ```
 
-### Returns
-
-`Promise`\<`boolean`\>
-
-### Inherited from
+Sets the lifecycle status and reports it via the status reporter.
 
-[`AbstractCreatable`](#AbstractCreatable).[`start`](AbstractCreatable.md#start)
+#### Parameters
 
-***
+##### value
 
-### stop()
+`"creating"` | `"created"` | `"starting"` | `"started"` | `"stopping"` | `"stopped"`
 
-```ts
-stop(): Promise<boolean>;
-```
+##### progress?
 
-### Returns
+`number`
 
-`Promise`\<`boolean`\>
+#### Returns
 
-### Inherited from
+`void`
 
-[`AbstractCreatable`](#AbstractCreatable).[`stop`](AbstractCreatable.md#stop)
+#### Inherited from
 
-***
+[`AbstractCreatable`](#AbstractCreatable).[`setStatus`](AbstractCreatable.md#setstatus)
 
-### \_noOverride()
+### Call Signature
 
 ```ts
-protected _noOverride(functionName): void;
+protected setStatus(value, error?): void;
 ```
 
-### Parameters
+Sets the lifecycle status and reports it via the status reporter.
 
-#### functionName
+#### Parameters
 
-`string` = `...`
+##### value
 
-### Returns
+`"error"`
+
+##### error?
+
+`Error`
+
+#### Returns
 
 `void`
 
-### Inherited from
+#### Inherited from
 
-[`AbstractCreatable`](#AbstractCreatable).[`_noOverride`](AbstractCreatable.md#_nooverride)
+[`AbstractCreatable`](#AbstractCreatable).[`setStatus`](AbstractCreatable.md#setstatus)
 
 ***
 
@@ -1678,6 +2235,8 @@ protected _noOverride(functionName): void;
 protected startHandler(): Promisable<void>;
 ```
 
+Override in subclasses to define start behavior. Throw an error on failure.
+
 ### Returns
 
 `Promisable`\<`void`\>
@@ -1694,6 +2253,8 @@ protected startHandler(): Promisable<void>;
 protected stopHandler(): Promisable<void>;
 ```
 
+Override in subclasses to define stop behavior. Throw an error on failure.
+
 ### Returns
 
 `Promisable`\<`void`\>
@@ -1713,6 +2274,8 @@ static factory<T>(
 labels?): CreatableFactory<T>;
 ```
 
+Creates a factory that produces instances of this class with pre-configured params and labels.
+
 ### Type Parameters
 
 #### T
@@ -1729,10 +2292,14 @@ labels?): CreatableFactory<T>;
 
 `Partial`\<`T`\[`"params"`\]\>
 
+Default parameters for instances created by the factory
+
 #### labels?
 
 [`Labels`](#../interfaces/Labels)
 
+Labels to assign to created instances
+
 ### Returns
 
 [`CreatableFactory`](#../interfaces/CreatableFactory)\<`T`\>
@@ -2017,6 +2584,9 @@ once<TEventName>(eventName, listener): () => void;
 
 ***
 
+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
 
 ### T
@@ -2064,6 +2634,8 @@ labels?): Factory<T>;
 creatable: Creatable<T>;
 ```
 
+The Creatable class this factory delegates creation to.
+
 ***
 
 ### defaultParams?
@@ -2072,6 +2644,8 @@ creatable: Creatable<T>;
 optional defaultParams: Partial<T["params"]>;
 ```
 
+Default parameters merged into every `create` call.
+
 ***
 
 ### labels?
@@ -2080,6 +2654,8 @@ optional defaultParams: Partial<T["params"]>;
 optional labels: Labels;
 ```
 
+Labels identifying resources created by this factory.
+
 ## Methods
 
 ### withParams()
@@ -2091,6 +2667,8 @@ static withParams<T>(
 labels?): Factory<T>;
 ```
 
+Creates a new Factory instance with the given default params and labels.
+
 ### Type Parameters
 
 #### T
@@ -2103,14 +2681,20 @@ labels?): Factory<T>;
 
 [`Creatable`](#../interfaces/Creatable)\<`T`\>
 
+The Creatable class to wrap
+
 #### params?
 
 `Partial`\<`T`\[`"params"`\]\>
 
+Default parameters for new instances
+
 #### labels?
 
 [`Labels`](#../interfaces/Labels) = `{}`
 
+Labels to assign to created instances
+
 ### Returns
 
 `Factory`\<`T`\>
@@ -2123,12 +2707,16 @@ labels?): Factory<T>;
 create(params?): Promise<T>;
 ```
 
+Creates a new instance, merging the provided params over the factory defaults.
+
 ### Parameters
 
 #### params?
 
 `Partial`\<`T`\[`"params"`\]\>
 
+Optional parameters to override the factory defaults
+
 ### Returns
 
 `Promise`\<`T`\>
@@ -2261,6 +2849,10 @@ True of the source object has all the labels from the required set
 
 ***
 
+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`](#CreatableWithFactory)
@@ -2279,6 +2871,8 @@ True of the source object has all the labels from the required set
 new Creatable(key, params): T & AbstractCreatable<T["params"], EventData>;
 ```
 
+Constructs a new raw instance. Should not be called directly; use `create` instead.
+
 ### Parameters
 
 #### key
@@ -2301,6 +2895,8 @@ new Creatable(key, params): T & AbstractCreatable<T["params"], EventData>;
 optional defaultLogger: Logger;
 ```
 
+Optional default logger shared across instances created by this class.
+
 ## Methods
 
 ### create()
@@ -2309,6 +2905,8 @@ optional defaultLogger: Logger;
 create<T>(this, params?): Promise<T>;
 ```
 
+Asynchronously creates and initializes a new instance with the given params.
+
 ### Type Parameters
 
 #### T
@@ -2337,6 +2935,8 @@ create<T>(this, params?): Promise<T>;
 createHandler<T>(this, instance): Promisable<T>;
 ```
 
+Hook called after construction to perform additional initialization on the instance.
+
 ### Type Parameters
 
 #### T
@@ -2362,9 +2962,11 @@ createHandler<T>(this, instance): Promisable<T>;
 ### paramsHandler()
 
 ```ts
-paramsHandler<T>(this, params?): Promisable<T["params"]>;
+paramsHandler<T>(this, params?): Promisable<T["params"] & RequiredCreatableParams<void>>;
 ```
 
+Hook called to validate and transform params before instance construction.
+
 ### Type Parameters
 
 #### T
@@ -2383,7 +2985,7 @@ paramsHandler<T>(this, params?): Promisable<T["params"]>;
 
 ### Returns
 
-`Promisable`\<`T`\[`"params"`\]\>
+`Promisable`\<`T`\[`"params"`\] & [`RequiredCreatableParams`](#RequiredCreatableParams)\<`void`\>\>
 
   ### <a id="CreatableFactory"></a>CreatableFactory
 
@@ -2391,6 +2993,9 @@ paramsHandler<T>(this, params?): Promisable<T["params"]>;
 
 ***
 
+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`](#Creatable)\<`T`\>, 
@@ -2414,6 +3019,8 @@ paramsHandler<T>(this, params?): Promisable<T["params"]>;
 create(this, params?): Promise<T>;
 ```
 
+Creates a new instance, merging the provided params with the factory's defaults.
+
 ### Parameters
 
 #### this
@@ -2434,6 +3041,8 @@ create(this, params?): Promise<T>;
 
 ***
 
+Represents a created instance with a managed lifecycle (start/stop) and event emission.
+
 ## Extends
 
 - `EventEmitter`\<`TEventData`\>
@@ -2456,6 +3065,8 @@ create(this, params?): Promise<T>;
 eventData: TEventData;
 ```
 
+The event data type associated with this instance.
+
 ### Overrides
 
 ```ts
@@ -2467,9 +3078,11 @@ EventEmitter.eventData
 ### name
 
 ```ts
-name: string;
+name: CreatableName;
 ```
 
+The name identifier for this instance.
+
 ***
 
 ### params
@@ -2478,6 +3091,36 @@ name: string;
 params: TParams;
 ```
 
+The parameters used to configure this instance.
+
+***
+
+### start()
+
+```ts
+start: () => Promise<boolean>;
+```
+
+Starts the instance. Resolves to true if started successfully.
+
+### Returns
+
+`Promise`\<`boolean`\>
+
+***
+
+### stop()
+
+```ts
+stop: () => Promise<boolean>;
+```
+
+Stops the instance. Resolves to true if stopped successfully.
+
+### Returns
+
+`Promise`\<`boolean`\>
+
 ## Methods
 
 ### clearListeners()
@@ -2750,9 +3393,11 @@ EventEmitter.once
 
 ***
 
+Parameters for creating a creatable instance, combining required params with emitter params.
+
 ## Extends
 
-- `BaseEmitterParams`
+- [`RequiredCreatableParams`](#RequiredCreatableParams).`BaseEmitterParams`
 
 ## Properties
 
@@ -2764,9 +3409,7 @@ optional logger: Logger;
 
 ### Inherited from
 
-```ts
-BaseEmitterParams.logger
-```
+[`RequiredCreatableParams`](#RequiredCreatableParams).[`logger`](RequiredCreatableParams.md#logger)
 
 ***
 
@@ -2778,9 +3421,7 @@ optional meterProvider: MeterProvider;
 
 ### Inherited from
 
-```ts
-BaseEmitterParams.meterProvider
-```
+[`RequiredCreatableParams`](#RequiredCreatableParams).[`meterProvider`](RequiredCreatableParams.md#meterprovider)
 
 ***
 
@@ -2792,18 +3433,22 @@ optional traceProvider: TracerProvider;
 
 ### Inherited from
 
-```ts
-BaseEmitterParams.traceProvider
-```
+[`RequiredCreatableParams`](#RequiredCreatableParams).[`traceProvider`](RequiredCreatableParams.md#traceprovider)
 
 ***
 
 ### name?
 
 ```ts
-optional name: string;
+optional name: CreatableName;
 ```
 
+Optional name identifying this creatable instance.
+
+### Inherited from
+
+[`RequiredCreatableParams`](#RequiredCreatableParams).[`name`](RequiredCreatableParams.md#name)
+
 ***
 
 ### statusReporter?
@@ -2812,17 +3457,25 @@ optional name: string;
 optional statusReporter: CreatableStatusReporter<void>;
 ```
 
+Optional reporter for broadcasting status changes.
+
+### Inherited from
+
+[`RequiredCreatableParams`](#RequiredCreatableParams).[`statusReporter`](RequiredCreatableParams.md#statusreporter)
+
   ### <a id="CreatableStatusReporter"></a>CreatableStatusReporter
 
 [**@xylabs/creatable**](#../README)
 
 ***
 
+Reports status changes for a creatable, supporting progress tracking and error reporting.
+
 ## Type Parameters
 
-### T
+### TAdditionalStatus
 
-`T` *extends* `void` \| `string` = `void`
+`TAdditionalStatus` *extends* `void` \| `string` = `void`
 
 ## Methods
 
@@ -2834,20 +3487,22 @@ optional statusReporter: CreatableStatusReporter<void>;
 report(
    name, 
    status, 
-   progress?): void;
+   progress): void;
 ```
 
+Report a non-error status with a numeric progress value.
+
 #### Parameters
 
 ##### name
 
-`string`
+`BaseClassName`
 
 ##### status
 
-`Exclude`\<`T` *extends* `void` ? [`CreatableStatus`](#../type-aliases/CreatableStatus) : `T` \| [`CreatableStatus`](#../type-aliases/CreatableStatus), `"error"`\>
+`"creating"` | `"created"` | `"starting"` | `"started"` | `"stopping"` | `"stopped"` | `Exclude`\<`TAdditionalStatus` *extends* `void` ? [`StandardCreatableStatus`](#../type-aliases/StandardCreatableStatus) : `TAdditionalStatus`, `"error"`\>
 
-##### progress?
+##### progress
 
 `number`
 
@@ -2861,25 +3516,49 @@ report(
 report(
    name, 
    status, 
-   error?): void;
+   error): void;
 ```
 
+Report an error status with the associated Error.
+
 #### Parameters
 
 ##### name
 
-`string`
+`BaseClassName`
 
 ##### status
 
-`Extract`\<`T` *extends* `void` ? [`CreatableStatus`](#../type-aliases/CreatableStatus) : `T` \| [`CreatableStatus`](#../type-aliases/CreatableStatus), `"error"`\>
+`"error"` | `Extract`\<`TAdditionalStatus` *extends* `void` ? [`StandardCreatableStatus`](#../type-aliases/StandardCreatableStatus) : `TAdditionalStatus`, `"error"`\>
 
-##### error?
+##### error
 
 `Error`
 
 #### Returns
 
+`void`
+
+### Call Signature
+
+```ts
+report(name, status): void;
+```
+
+Report a status change without progress or error details.
+
+#### Parameters
+
+##### name
+
+`BaseClassName`
+
+##### status
+
+[`CreatableStatus`](#../type-aliases/CreatableStatus)\<`TAdditionalStatus`\>
+
+#### Returns
+
 `void`
 
   ### <a id="CreatableWithFactory"></a>CreatableWithFactory
@@ -2888,6 +3567,8 @@ report(
 
 ***
 
+Extends Creatable with a `factory` method that produces pre-configured CreatableFactory instances.
+
 ## Extends
 
 - [`Creatable`](#Creatable)\<`T`\>
@@ -2906,6 +3587,8 @@ report(
 new CreatableWithFactory(key, params): T & AbstractCreatable<T["params"], EventData>;
 ```
 
+Constructs a new raw instance. Should not be called directly; use `create` instead.
+
 ### Parameters
 
 #### key
@@ -2932,6 +3615,8 @@ new CreatableWithFactory(key, params): T & AbstractCreatable<T["params"], EventD
 optional defaultLogger: Logger;
 ```
 
+Optional default logger shared across instances created by this class.
+
 ### Inherited from
 
 [`Creatable`](#Creatable).[`defaultLogger`](Creatable.md#defaultlogger)
@@ -2944,6 +3629,8 @@ optional defaultLogger: Logger;
 create<T>(this, params?): Promise<T>;
 ```
 
+Asynchronously creates and initializes a new instance with the given params.
+
 ### Type Parameters
 
 #### T
@@ -2976,6 +3663,8 @@ create<T>(this, params?): Promise<T>;
 createHandler<T>(this, instance): Promisable<T>;
 ```
 
+Hook called after construction to perform additional initialization on the instance.
+
 ### Type Parameters
 
 #### T
@@ -3005,9 +3694,11 @@ createHandler<T>(this, instance): Promisable<T>;
 ### paramsHandler()
 
 ```ts
-paramsHandler<T>(this, params?): Promisable<T["params"]>;
+paramsHandler<T>(this, params?): Promisable<T["params"] & RequiredCreatableParams<void>>;
 ```
 
+Hook called to validate and transform params before instance construction.
+
 ### Type Parameters
 
 #### T
@@ -3026,7 +3717,7 @@ paramsHandler<T>(this, params?): Promisable<T["params"]>;
 
 ### Returns
 
-`Promisable`\<`T`\[`"params"`\]\>
+`Promisable`\<`T`\[`"params"`\] & [`RequiredCreatableParams`](#RequiredCreatableParams)\<`void`\>\>
 
 ### Inherited from
 
@@ -3043,6 +3734,8 @@ factory<T>(
 labels?): CreatableFactory<T>;
 ```
 
+Creates a factory with the given default params and labels.
+
 ### Type Parameters
 
 #### T
@@ -3078,9 +3771,93 @@ Object used to represent labels identifying a resource.
 ## Indexable
 
 ```ts
-[key: string]: undefined | string
+[key: string]: string | undefined
+```
+
+  ### <a id="RequiredCreatableParams"></a>RequiredCreatableParams
+
+[**@xylabs/creatable**](#../README)
+
+***
+
+The minimum required parameters for constructing a creatable.
+
+## Extends
+
+- `BaseEmitterParams`
+
+## Extended by
+
+- [`CreatableParams`](#CreatableParams)
+
+## Type Parameters
+
+### TAdditionalStatus
+
+`TAdditionalStatus` *extends* [`CreatableStatus`](#../type-aliases/CreatableStatus) \| `void` = `void`
+
+## Properties
+
+### logger?
+
+```ts
+optional logger: Logger;
+```
+
+### Inherited from
+
+```ts
+BaseEmitterParams.logger
+```
+
+***
+
+### meterProvider?
+
+```ts
+optional meterProvider: MeterProvider;
+```
+
+### Inherited from
+
+```ts
+BaseEmitterParams.meterProvider
+```
+
+***
+
+### traceProvider?
+
+```ts
+optional traceProvider: TracerProvider;
+```
+
+### Inherited from
+
+```ts
+BaseEmitterParams.traceProvider
+```
+
+***
+
+### name?
+
+```ts
+optional name: CreatableName;
+```
+
+Optional name identifying this creatable instance.
+
+***
+
+### statusReporter?
+
+```ts
+optional statusReporter: CreatableStatusReporter<TAdditionalStatus>;
 ```
 
+Optional reporter for broadcasting status changes.
+
   ### <a id="WithLabels"></a>WithLabels
 
 [**@xylabs/creatable**](#../README)
@@ -3137,6 +3914,8 @@ optional labels: T;
 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
 
 [**@xylabs/creatable**](#../README)
@@ -3144,7 +3923,27 @@ type CreatableName = Exclude<string, "creatable-name-reserved-32546239486"> & Ba
 ***
 
 ```ts
-type CreatableStatus = 
+type CreatableStatus<TAdditionalStatus> = 
+  | StandardCreatableStatus
+  | TAdditionalStatus extends void ? StandardCreatableStatus : TAdditionalStatus;
+```
+
+A creatable's status, optionally extended with additional custom status values.
+
+## Type Parameters
+
+### TAdditionalStatus
+
+`TAdditionalStatus` *extends* `void` \| `string` = `void`
+
+  ### <a id="StandardCreatableStatus"></a>StandardCreatableStatus
+
+[**@xylabs/creatable**](#../README)
+
+***
+
+```ts
+type StandardCreatableStatus = 
   | "creating"
   | "created"
   | "starting"
@@ -3154,6 +3953,8 @@ type CreatableStatus =
   | "error";
 ```
 
+The standard lifecycle statuses a creatable can transition through.
+
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)