@lite-fsm/entities 0.1.0-alpha.0

package/dist/runtime/store-types.d.ts

@@ -0,0 +1,81 @@
+import type { MachineStore } from "@lite-fsm/core";
+import type { EntityIndex } from "../plugin";
+import type { EntityAccess } from "./access";
+import type { EntityTemplateMetadata } from "./compile";
+import type { EntityReactRuntime } from "./react";
+export type EntityPublicStateSlice = {
+    readonly storage: "entity";
+    readonly version: number;
+    readonly count: number;
+    readonly capacity: number;
+};
+export type EntityColumn = Float32Array | Int16Array | Int32Array | Uint8Array | string[];
+export type EntityStore = {
+    count: number;
+    capacity: number;
+    ids: string[];
+    indexById: Record<string, EntityIndex>;
+    alive: Uint8Array;
+    generation: Uint32Array;
+    groupTagByIndex: string[];
+    entitiesByGroupTag: Record<string, EntityIndex[]>;
+    groupTagPosition: Int32Array;
+    freeList: EntityIndex[];
+    version: number;
+};
+export type EntityActorRowRef = {
+    readonly store: ColumnarActorStore;
+    readonly entity: EntityIndex;
+    readonly groupTag: string;
+    entityRowsPosition: number;
+    groupRowsPosition: number;
+};
+export type ColumnarActorStore = {
+    readonly storeId: number;
+    readonly templateKey: string;
+    readonly metadata: EntityTemplateMetadata;
+    capacity: number;
+    count: number;
+    version: number;
+    presence: Uint8Array;
+    stateCode: Int16Array;
+    prevStateCode: Int16Array;
+    rowVersion: Uint32Array;
+    stateBuckets: EntityIndex[][];
+    statePosition: Int32Array;
+    acceptedScratch: EntityIndex[];
+    defaultTransitionSourceStateScratch: number[];
+    pendingPrevStateCodeSync: EntityIndex[];
+    pendingPrevStateCodeSyncMark: Uint32Array;
+    pendingPrevStateCodeSyncToken: number;
+    routingScratchVersion: number;
+    acceptStateBucketsByEventCode: EntityIndex[][][];
+    columns: Record<string, EntityColumn>;
+    resources: Record<string, unknown>;
+    resourceViews: Record<string, unknown>;
+    reducerSelf: EntityReducerSelfCache;
+    publicSlice: EntityPublicStateSlice;
+};
+export type EntityReducerSelfCache = Record<string, unknown> & {
+    indices: readonly EntityIndex[];
+    readonly states: EntityTemplateMetadata["stateCodeByName"];
+    presence: Uint8Array;
+    stateCode: Int16Array;
+    prevStateCode: Int16Array;
+    rowVersion: Uint32Array;
+    has(entity: EntityIndex): boolean;
+    entityId(entity: EntityIndex): string;
+};
+export type EntityRuntimeState = {
+    readonly entityStore: EntityStore;
+    readonly actorStores: Record<string, ColumnarActorStore>;
+    readonly actorStoresById: ColumnarActorStore[];
+    readonly eventCodeByType: Readonly<Record<string, number>>;
+    readonly eventTypesByCode: readonly string[];
+    readonly templatesByEventCode: readonly (readonly ColumnarActorStore[])[];
+    actorRowsByEntity: EntityActorRowRef[][];
+    actorRowsByGroupTag: Record<string, EntityActorRowRef[]>;
+    routingScratchVersion: number;
+    readonly access: EntityAccess<MachineStore>;
+    react?: EntityReactRuntime;
+};

package/dist/runtime/transaction.d.cts

@@ -0,0 +1,104 @@
+import type { AnyEvent, ReadonlyManagerAction } from "@lite-fsm/core";
+import type { EntityIndex } from "../plugin";
+import type { EntitySpawnDescriptor } from "../spawn";
+import type { ColumnarActorStore, EntityActorRowRef, EntityRuntimeState } from "./state";
+type RuntimeCarrier = {
+    readonly runtime: Map<string, unknown>;
+};
+export type StagedActorSpawn = {
+    readonly templateKey: string;
+    readonly payload: Record<string, unknown>;
+};
+export type StagedEntitySpawn = {
+    readonly id: string;
+    readonly groupTag: string;
+    readonly actors: readonly StagedActorSpawn[];
+};
+export type EntityDispatchTransaction = {
+    readonly runtime: EntityRuntimeState;
+    stagedSpawns: readonly StagedEntitySpawn[];
+    scheduledDespawns: EntityIndex[];
+    despawnScheduled: Uint8Array;
+    despawnRowHints: EntityDespawnRowHint[];
+    terminalRows: EntityActorTerminalRow[];
+    effectBatches: EntityEffectBatch[];
+    reactionBatches: EntityReactionBatch[];
+};
+export type EntityDespawnRowHint = {
+    readonly storeId: number;
+    readonly entity: EntityIndex;
+    readonly bucketStateCode: number;
+};
+export type EntityActorTerminalRow = {
+    readonly store: ColumnarActorStore;
+    readonly entity: EntityIndex;
+};
+export type EntityCleanupRemovalBatch = {
+    readonly store: ColumnarActorStore;
+    readonly rows: EntityActorRowRef[];
+    readonly bucketStateCodes: Array<number | undefined>;
+    bucketStateCodesActive: boolean;
+};
+export type EntityCleanupLifecycleBatch = {
+    readonly store: ColumnarActorStore;
+    readonly indices: EntityIndex[];
+};
+export type EntityCleanupScratch = {
+    readonly entities: EntityIndex[];
+    readonly removalBatchesByStoreId: Array<EntityCleanupRemovalBatch | undefined>;
+    readonly removalTouchedStoreIds: number[];
+    readonly lifecycleBatchesByStoreId: Array<EntityCleanupLifecycleBatch | undefined>;
+    readonly lifecycleTouchedStoreIds: number[];
+};
+export type EntityEffectBatch = {
+    readonly store: ColumnarActorStore;
+    readonly stateCode: number;
+    readonly indices: readonly EntityIndex[];
+    readonly capturedEntries?: readonly CapturedEntityScopeEntry[];
+    readonly storeVersion?: number;
+    readonly entityStoreVersion?: number;
+};
+export type EntityReactionBatch = {
+    readonly store: ColumnarActorStore;
+    readonly eventCode: number;
+    readonly ownership: EntityReactionBatchOwnership;
+    readonly indices: readonly EntityIndex[];
+};
+export type CapturedEntityScopeEntry = {
+    readonly entity: EntityIndex;
+    readonly generation: number;
+    readonly id: string;
+};
+type ExplicitDespawnRequest = {
+    readonly mode: "ids";
+    readonly ids: readonly string[];
+} | {
+    readonly mode: "scope";
+    readonly entries: readonly CapturedEntityScopeEntry[];
+};
+export type EntityReactionBatchOwnership = "borrowed" | "owned";
+type ScheduleEntityReactionBatchOptions = {
+    readonly ownership?: EntityReactionBatchOwnership;
+};
+export declare const ENTITY_DESPAWN_ACTION_TYPE = "LITE_FSM_ENTITY_DESPAWN";
+export declare const createEntityDespawnOptions: (request: ExplicitDespawnRequest) => object;
+export declare const prepareEntityTransaction: (carrier: RuntimeCarrier, runtime: EntityRuntimeState) => EntityDispatchTransaction;
+export declare const getEntityTransaction: (carrier: RuntimeCarrier) => EntityDispatchTransaction | undefined;
+export declare const stageSpawnAction: (carrier: RuntimeCarrier & {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly skipDelivery: boolean;
+}, spawn: EntitySpawnDescriptor) => void;
+export declare const getStagedSpawns: (carrier: RuntimeCarrier) => readonly StagedEntitySpawn[];
+export declare const scheduleEntityDespawn: (transaction: EntityDispatchTransaction, entity: EntityIndex) => boolean;
+export declare const scheduleDespawnRowHint: (transaction: EntityDispatchTransaction, store: ColumnarActorStore, entity: EntityIndex, bucketStateCode: number) => boolean;
+export declare const getDespawnRowHintBucketStateCode: (transaction: EntityDispatchTransaction, storeId: number, entity: EntityIndex) => number | undefined;
+export declare const clearDespawnRowHints: (transaction: EntityDispatchTransaction) => void;
+export declare const consumeScheduledDespawns: (transaction: EntityDispatchTransaction) => readonly EntityIndex[];
+export declare const beginEntityCleanupScratch: (transaction: EntityDispatchTransaction) => EntityCleanupScratch;
+export declare const finishEntityCleanupScratch: (transaction: EntityDispatchTransaction, cleanup: EntityCleanupScratch) => void;
+export declare const appendCleanupRemovalRow: (cleanup: EntityCleanupScratch, store: ColumnarActorStore, row: EntityActorRowRef, bucketStateCode: number | undefined) => void;
+export declare const appendCleanupLifecycleIndex: (cleanup: EntityCleanupScratch, store: ColumnarActorStore, entity: EntityIndex) => void;
+export declare const scheduleEntityEffectBatch: (transaction: EntityDispatchTransaction | undefined, store: ColumnarActorStore, stateCode: number, indices: readonly EntityIndex[], capturedEntries?: readonly CapturedEntityScopeEntry[]) => void;
+export declare const createEntityReactionBatch: (transaction: EntityDispatchTransaction | undefined, store: ColumnarActorStore, eventCode: number | undefined, indices: readonly EntityIndex[], options?: ScheduleEntityReactionBatchOptions) => EntityReactionBatch | undefined;
+export declare const scheduleEntityReactionBatch: (transaction: EntityDispatchTransaction | undefined, store: ColumnarActorStore, eventCode: number | undefined, indices: readonly EntityIndex[], options?: ScheduleEntityReactionBatchOptions) => void;
+export {};

package/dist/runtime/transaction.d.ts

@@ -0,0 +1,104 @@
+import type { AnyEvent, ReadonlyManagerAction } from "@lite-fsm/core";
+import type { EntityIndex } from "../plugin";
+import type { EntitySpawnDescriptor } from "../spawn";
+import type { ColumnarActorStore, EntityActorRowRef, EntityRuntimeState } from "./state";
+type RuntimeCarrier = {
+    readonly runtime: Map<string, unknown>;
+};
+export type StagedActorSpawn = {
+    readonly templateKey: string;
+    readonly payload: Record<string, unknown>;
+};
+export type StagedEntitySpawn = {
+    readonly id: string;
+    readonly groupTag: string;
+    readonly actors: readonly StagedActorSpawn[];
+};
+export type EntityDispatchTransaction = {
+    readonly runtime: EntityRuntimeState;
+    stagedSpawns: readonly StagedEntitySpawn[];
+    scheduledDespawns: EntityIndex[];
+    despawnScheduled: Uint8Array;
+    despawnRowHints: EntityDespawnRowHint[];
+    terminalRows: EntityActorTerminalRow[];
+    effectBatches: EntityEffectBatch[];
+    reactionBatches: EntityReactionBatch[];
+};
+export type EntityDespawnRowHint = {
+    readonly storeId: number;
+    readonly entity: EntityIndex;
+    readonly bucketStateCode: number;
+};
+export type EntityActorTerminalRow = {
+    readonly store: ColumnarActorStore;
+    readonly entity: EntityIndex;
+};
+export type EntityCleanupRemovalBatch = {
+    readonly store: ColumnarActorStore;
+    readonly rows: EntityActorRowRef[];
+    readonly bucketStateCodes: Array<number | undefined>;
+    bucketStateCodesActive: boolean;
+};
+export type EntityCleanupLifecycleBatch = {
+    readonly store: ColumnarActorStore;
+    readonly indices: EntityIndex[];
+};
+export type EntityCleanupScratch = {
+    readonly entities: EntityIndex[];
+    readonly removalBatchesByStoreId: Array<EntityCleanupRemovalBatch | undefined>;
+    readonly removalTouchedStoreIds: number[];
+    readonly lifecycleBatchesByStoreId: Array<EntityCleanupLifecycleBatch | undefined>;
+    readonly lifecycleTouchedStoreIds: number[];
+};
+export type EntityEffectBatch = {
+    readonly store: ColumnarActorStore;
+    readonly stateCode: number;
+    readonly indices: readonly EntityIndex[];
+    readonly capturedEntries?: readonly CapturedEntityScopeEntry[];
+    readonly storeVersion?: number;
+    readonly entityStoreVersion?: number;
+};
+export type EntityReactionBatch = {
+    readonly store: ColumnarActorStore;
+    readonly eventCode: number;
+    readonly ownership: EntityReactionBatchOwnership;
+    readonly indices: readonly EntityIndex[];
+};
+export type CapturedEntityScopeEntry = {
+    readonly entity: EntityIndex;
+    readonly generation: number;
+    readonly id: string;
+};
+type ExplicitDespawnRequest = {
+    readonly mode: "ids";
+    readonly ids: readonly string[];
+} | {
+    readonly mode: "scope";
+    readonly entries: readonly CapturedEntityScopeEntry[];
+};
+export type EntityReactionBatchOwnership = "borrowed" | "owned";
+type ScheduleEntityReactionBatchOptions = {
+    readonly ownership?: EntityReactionBatchOwnership;
+};
+export declare const ENTITY_DESPAWN_ACTION_TYPE = "LITE_FSM_ENTITY_DESPAWN";
+export declare const createEntityDespawnOptions: (request: ExplicitDespawnRequest) => object;
+export declare const prepareEntityTransaction: (carrier: RuntimeCarrier, runtime: EntityRuntimeState) => EntityDispatchTransaction;
+export declare const getEntityTransaction: (carrier: RuntimeCarrier) => EntityDispatchTransaction | undefined;
+export declare const stageSpawnAction: (carrier: RuntimeCarrier & {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly skipDelivery: boolean;
+}, spawn: EntitySpawnDescriptor) => void;
+export declare const getStagedSpawns: (carrier: RuntimeCarrier) => readonly StagedEntitySpawn[];
+export declare const scheduleEntityDespawn: (transaction: EntityDispatchTransaction, entity: EntityIndex) => boolean;
+export declare const scheduleDespawnRowHint: (transaction: EntityDispatchTransaction, store: ColumnarActorStore, entity: EntityIndex, bucketStateCode: number) => boolean;
+export declare const getDespawnRowHintBucketStateCode: (transaction: EntityDispatchTransaction, storeId: number, entity: EntityIndex) => number | undefined;
+export declare const clearDespawnRowHints: (transaction: EntityDispatchTransaction) => void;
+export declare const consumeScheduledDespawns: (transaction: EntityDispatchTransaction) => readonly EntityIndex[];
+export declare const beginEntityCleanupScratch: (transaction: EntityDispatchTransaction) => EntityCleanupScratch;
+export declare const finishEntityCleanupScratch: (transaction: EntityDispatchTransaction, cleanup: EntityCleanupScratch) => void;
+export declare const appendCleanupRemovalRow: (cleanup: EntityCleanupScratch, store: ColumnarActorStore, row: EntityActorRowRef, bucketStateCode: number | undefined) => void;
+export declare const appendCleanupLifecycleIndex: (cleanup: EntityCleanupScratch, store: ColumnarActorStore, entity: EntityIndex) => void;
+export declare const scheduleEntityEffectBatch: (transaction: EntityDispatchTransaction | undefined, store: ColumnarActorStore, stateCode: number, indices: readonly EntityIndex[], capturedEntries?: readonly CapturedEntityScopeEntry[]) => void;
+export declare const createEntityReactionBatch: (transaction: EntityDispatchTransaction | undefined, store: ColumnarActorStore, eventCode: number | undefined, indices: readonly EntityIndex[], options?: ScheduleEntityReactionBatchOptions) => EntityReactionBatch | undefined;
+export declare const scheduleEntityReactionBatch: (transaction: EntityDispatchTransaction | undefined, store: ColumnarActorStore, eventCode: number | undefined, indices: readonly EntityIndex[], options?: ScheduleEntityReactionBatchOptions) => void;
+export {};

package/dist/runtime/transitionTrace.d.cts

@@ -0,0 +1,19 @@
+type RuntimeCarrier = {
+    readonly runtime: Map<string, unknown>;
+};
+type EntityTransitionTracePhaseMetadata = {
+    readonly runtimeKind?: string;
+};
+export type EntityTransitionTraceSession = {
+    readonly depth: number;
+    now(): number;
+    record(key: string, startedAt: number, metadata?: EntityTransitionTracePhaseMetadata): void;
+    count(key: string, value?: number): void;
+    finish(status: "ok" | "error"): void;
+};
+export declare const readEntityTransitionTraceSession: (carrier: RuntimeCarrier) => EntityTransitionTraceSession | undefined;
+export declare const recordEntityTracePhase: (trace: EntityTransitionTraceSession | undefined, key: string, startedAt: number | undefined) => void;
+export declare const recordEntityTraceCounter: (trace: EntityTransitionTraceSession | undefined, key: string, value?: number) => void;
+export declare const tracePhase: <T>(trace: EntityTransitionTraceSession | undefined, key: string, fn: () => T) => T;
+export declare const traceDispatchPhase: <T>(carrier: RuntimeCarrier, key: string, fn: () => T) => T;
+export {};

package/dist/runtime/transitionTrace.d.ts

@@ -0,0 +1,19 @@
+type RuntimeCarrier = {
+    readonly runtime: Map<string, unknown>;
+};
+type EntityTransitionTracePhaseMetadata = {
+    readonly runtimeKind?: string;
+};
+export type EntityTransitionTraceSession = {
+    readonly depth: number;
+    now(): number;
+    record(key: string, startedAt: number, metadata?: EntityTransitionTracePhaseMetadata): void;
+    count(key: string, value?: number): void;
+    finish(status: "ok" | "error"): void;
+};
+export declare const readEntityTransitionTraceSession: (carrier: RuntimeCarrier) => EntityTransitionTraceSession | undefined;
+export declare const recordEntityTracePhase: (trace: EntityTransitionTraceSession | undefined, key: string, startedAt: number | undefined) => void;
+export declare const recordEntityTraceCounter: (trace: EntityTransitionTraceSession | undefined, key: string, value?: number) => void;
+export declare const tracePhase: <T>(trace: EntityTransitionTraceSession | undefined, key: string, fn: () => T) => T;
+export declare const traceDispatchPhase: <T>(carrier: RuntimeCarrier, key: string, fn: () => T) => T;
+export {};

package/dist/schema.d.cts

@@ -0,0 +1,90 @@
+export declare const descriptorMarker: unique symbol;
+export declare const resourceDescriptorMarker: unique symbol;
+type NumericDescriptorKind = "f32" | "i16" | "i32" | "u8";
+type DescriptorKind = NumericDescriptorKind | "string";
+type DescriptorDefault = number | string;
+type ColumnForKind<Kind extends DescriptorKind> = Kind extends "f32" ? Float32Array : Kind extends "i16" ? Int16Array : Kind extends "i32" ? Int32Array : Kind extends "u8" ? Uint8Array : readonly string[];
+type ValueForKind<Kind extends DescriptorKind> = Kind extends NumericDescriptorKind ? number : string;
+type DescriptorOptions<Value extends DescriptorDefault> = {
+    readonly default?: Value;
+};
+type EntityDescriptorBase<Value, Column, Spawn> = {
+    readonly [descriptorMarker]: true;
+    readonly valueType?: Value;
+    readonly columnType?: Column;
+    readonly spawnType?: Spawn;
+};
+type EntityScalarDescriptor<Kind extends DescriptorKind> = EntityDescriptorBase<ValueForKind<Kind>, ColumnForKind<Kind>, ValueForKind<Kind>> & {
+    readonly kind: Kind;
+    readonly default?: ValueForKind<Kind>;
+};
+type EntityOptionalDescriptor<Inner extends EntityScalarDescriptor<DescriptorKind>> = EntityDescriptorBase<never, never, DescriptorSpawnValue<Inner> | null> & {
+    readonly kind: "optional";
+    readonly inner: Inner;
+};
+export type EntityResourceDescriptor<Owner, View, Exposed extends boolean> = {
+    readonly [resourceDescriptorMarker]: true;
+    readonly kind: "resource";
+    readonly factory: () => Owner;
+    readonly exposed: Exposed;
+    readonly ownerType?: Owner;
+    readonly viewType?: View;
+} & (Exposed extends true ? {
+    readonly expose: (resource: Owner) => View;
+} : {
+    readonly expose?: undefined;
+});
+export type EntityDescriptor = EntityScalarDescriptor<DescriptorKind>;
+export type AnyEntityResourceDescriptor = EntityResourceDescriptor<any, any, false> | EntityResourceDescriptor<any, any, true>;
+export type EntityContextDescriptor = EntityDescriptor | AnyEntityResourceDescriptor;
+export type EntitySpawnDescriptor = EntityDescriptor | EntityOptionalDescriptor<EntityDescriptor>;
+export type EntityColumnSchema = Readonly<Record<string, EntityDescriptor>>;
+export type EntityContextSchema = Readonly<Record<string, EntityContextDescriptor>>;
+export type EntityResourceSchema = Readonly<Record<string, AnyEntityResourceDescriptor>>;
+export type EntitySpawnSchema = Readonly<Record<string, EntitySpawnDescriptor>>;
+type DescriptorValue<Descriptor> = Descriptor extends {
+    readonly valueType?: infer Value;
+} ? Value : never;
+type DescriptorColumn<Descriptor> = Descriptor extends {
+    readonly columnType?: infer Column;
+} ? Column : never;
+type DescriptorSpawnValue<Descriptor> = Descriptor extends {
+    readonly spawnType?: infer Spawn;
+} ? Spawn : never;
+export declare const f32: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"f32">;
+export declare const i16: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"i16">;
+export declare const i32: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"i32">;
+export declare const u8: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"u8">;
+export declare const string: (opts?: DescriptorOptions<string>) => EntityScalarDescriptor<"string">;
+export declare const optional: <Inner extends EntityDescriptor>(inner: Inner) => EntityOptionalDescriptor<Inner>;
+export declare function resource<Owner>(factory: () => Owner): EntityResourceDescriptor<Owner, never, false>;
+export declare function resource<Owner, View>(factory: () => Owner, expose: (resource: Owner) => View): EntityResourceDescriptor<Owner, View, true>;
+export declare const isEntityResourceDescriptor: (value: unknown) => value is AnyEntityResourceDescriptor;
+export declare const validateEntitySchema: (machineKey: string, path: "initialContext" | "spawnSchema", schema: unknown) => void;
+type EntitySchemaColumnKey<Schema extends EntityContextSchema> = string extends keyof Schema ? string : {
+    readonly [Field in keyof Schema]: Schema[Field] extends EntityDescriptor ? Field : never;
+}[keyof Schema];
+type EntitySchemaResourceOwnerKey<Schema extends EntityContextSchema> = string extends keyof Schema ? never : {
+    readonly [Field in keyof Schema]: Schema[Field] extends EntityResourceDescriptor<any, any, boolean> ? Field : never;
+}[keyof Schema];
+type EntitySchemaResourceExposedKey<Schema extends EntityContextSchema> = string extends keyof Schema ? never : {
+    readonly [Field in keyof Schema]: Schema[Field] extends EntityResourceDescriptor<any, any, true> ? Field : never;
+}[keyof Schema];
+type ResourceOwner<Descriptor> = Descriptor extends EntityResourceDescriptor<infer Owner, any, boolean> ? Owner : never;
+type ResourceView<Descriptor> = Descriptor extends EntityResourceDescriptor<any, infer View, true> ? View : never;
+export type EntitySchemaValue<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaColumnKey<Schema>]: DescriptorValue<Schema[Field]>;
+};
+export type EntitySchemaColumns<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaColumnKey<Schema>]: DescriptorColumn<Schema[Field]>;
+};
+export type EntitySchemaResourceOwners<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaResourceOwnerKey<Schema>]: ResourceOwner<Schema[Field]>;
+};
+export type EntitySchemaResourceViews<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaResourceExposedKey<Schema>]: ResourceView<Schema[Field]>;
+};
+export type EntitySpawnPayload<Schema extends EntitySpawnSchema> = {
+    readonly [Field in keyof Schema]: DescriptorSpawnValue<Schema[Field]>;
+};
+export {};

package/dist/schema.d.ts

@@ -0,0 +1,90 @@
+export declare const descriptorMarker: unique symbol;
+export declare const resourceDescriptorMarker: unique symbol;
+type NumericDescriptorKind = "f32" | "i16" | "i32" | "u8";
+type DescriptorKind = NumericDescriptorKind | "string";
+type DescriptorDefault = number | string;
+type ColumnForKind<Kind extends DescriptorKind> = Kind extends "f32" ? Float32Array : Kind extends "i16" ? Int16Array : Kind extends "i32" ? Int32Array : Kind extends "u8" ? Uint8Array : readonly string[];
+type ValueForKind<Kind extends DescriptorKind> = Kind extends NumericDescriptorKind ? number : string;
+type DescriptorOptions<Value extends DescriptorDefault> = {
+    readonly default?: Value;
+};
+type EntityDescriptorBase<Value, Column, Spawn> = {
+    readonly [descriptorMarker]: true;
+    readonly valueType?: Value;
+    readonly columnType?: Column;
+    readonly spawnType?: Spawn;
+};
+type EntityScalarDescriptor<Kind extends DescriptorKind> = EntityDescriptorBase<ValueForKind<Kind>, ColumnForKind<Kind>, ValueForKind<Kind>> & {
+    readonly kind: Kind;
+    readonly default?: ValueForKind<Kind>;
+};
+type EntityOptionalDescriptor<Inner extends EntityScalarDescriptor<DescriptorKind>> = EntityDescriptorBase<never, never, DescriptorSpawnValue<Inner> | null> & {
+    readonly kind: "optional";
+    readonly inner: Inner;
+};
+export type EntityResourceDescriptor<Owner, View, Exposed extends boolean> = {
+    readonly [resourceDescriptorMarker]: true;
+    readonly kind: "resource";
+    readonly factory: () => Owner;
+    readonly exposed: Exposed;
+    readonly ownerType?: Owner;
+    readonly viewType?: View;
+} & (Exposed extends true ? {
+    readonly expose: (resource: Owner) => View;
+} : {
+    readonly expose?: undefined;
+});
+export type EntityDescriptor = EntityScalarDescriptor<DescriptorKind>;
+export type AnyEntityResourceDescriptor = EntityResourceDescriptor<any, any, false> | EntityResourceDescriptor<any, any, true>;
+export type EntityContextDescriptor = EntityDescriptor | AnyEntityResourceDescriptor;
+export type EntitySpawnDescriptor = EntityDescriptor | EntityOptionalDescriptor<EntityDescriptor>;
+export type EntityColumnSchema = Readonly<Record<string, EntityDescriptor>>;
+export type EntityContextSchema = Readonly<Record<string, EntityContextDescriptor>>;
+export type EntityResourceSchema = Readonly<Record<string, AnyEntityResourceDescriptor>>;
+export type EntitySpawnSchema = Readonly<Record<string, EntitySpawnDescriptor>>;
+type DescriptorValue<Descriptor> = Descriptor extends {
+    readonly valueType?: infer Value;
+} ? Value : never;
+type DescriptorColumn<Descriptor> = Descriptor extends {
+    readonly columnType?: infer Column;
+} ? Column : never;
+type DescriptorSpawnValue<Descriptor> = Descriptor extends {
+    readonly spawnType?: infer Spawn;
+} ? Spawn : never;
+export declare const f32: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"f32">;
+export declare const i16: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"i16">;
+export declare const i32: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"i32">;
+export declare const u8: (opts?: DescriptorOptions<number>) => EntityScalarDescriptor<"u8">;
+export declare const string: (opts?: DescriptorOptions<string>) => EntityScalarDescriptor<"string">;
+export declare const optional: <Inner extends EntityDescriptor>(inner: Inner) => EntityOptionalDescriptor<Inner>;
+export declare function resource<Owner>(factory: () => Owner): EntityResourceDescriptor<Owner, never, false>;
+export declare function resource<Owner, View>(factory: () => Owner, expose: (resource: Owner) => View): EntityResourceDescriptor<Owner, View, true>;
+export declare const isEntityResourceDescriptor: (value: unknown) => value is AnyEntityResourceDescriptor;
+export declare const validateEntitySchema: (machineKey: string, path: "initialContext" | "spawnSchema", schema: unknown) => void;
+type EntitySchemaColumnKey<Schema extends EntityContextSchema> = string extends keyof Schema ? string : {
+    readonly [Field in keyof Schema]: Schema[Field] extends EntityDescriptor ? Field : never;
+}[keyof Schema];
+type EntitySchemaResourceOwnerKey<Schema extends EntityContextSchema> = string extends keyof Schema ? never : {
+    readonly [Field in keyof Schema]: Schema[Field] extends EntityResourceDescriptor<any, any, boolean> ? Field : never;
+}[keyof Schema];
+type EntitySchemaResourceExposedKey<Schema extends EntityContextSchema> = string extends keyof Schema ? never : {
+    readonly [Field in keyof Schema]: Schema[Field] extends EntityResourceDescriptor<any, any, true> ? Field : never;
+}[keyof Schema];
+type ResourceOwner<Descriptor> = Descriptor extends EntityResourceDescriptor<infer Owner, any, boolean> ? Owner : never;
+type ResourceView<Descriptor> = Descriptor extends EntityResourceDescriptor<any, infer View, true> ? View : never;
+export type EntitySchemaValue<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaColumnKey<Schema>]: DescriptorValue<Schema[Field]>;
+};
+export type EntitySchemaColumns<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaColumnKey<Schema>]: DescriptorColumn<Schema[Field]>;
+};
+export type EntitySchemaResourceOwners<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaResourceOwnerKey<Schema>]: ResourceOwner<Schema[Field]>;
+};
+export type EntitySchemaResourceViews<Schema extends EntityContextSchema> = {
+    readonly [Field in EntitySchemaResourceExposedKey<Schema>]: ResourceView<Schema[Field]>;
+};
+export type EntitySpawnPayload<Schema extends EntitySpawnSchema> = {
+    readonly [Field in keyof Schema]: DescriptorSpawnValue<Schema[Field]>;
+};
+export {};

package/dist/spawn.d.cts

@@ -0,0 +1,56 @@
+import type { AnyEvent, MachineStore } from "@lite-fsm/core";
+import type { EntitySpawnPayload, EntitySpawnSchema } from "./schema";
+declare const spawnEventMarker: unique symbol;
+declare const entitySpawnMarker: unique symbol;
+export type SpawnEventDescriptor<Payload> = {
+    readonly [spawnEventMarker]: true;
+    readonly payloadType?: Payload;
+};
+type SpawnEventPayload<Descriptor> = Descriptor extends {
+    readonly payloadType?: infer Payload;
+} ? Payload : never;
+export type SpawnEventsConfig = Readonly<Record<string, SpawnEventDescriptor<unknown>>>;
+export type SpawnEventsFrom<SpawnEvents extends SpawnEventsConfig> = {
+    readonly [Type in keyof SpawnEvents & string]: {
+        readonly type: Type;
+        readonly payload: SpawnEventPayload<SpawnEvents[Type]>;
+    };
+}[keyof SpawnEvents & string];
+type EntityActorMachine = {
+    readonly storage: "entity";
+    readonly spawnSchema: EntitySpawnSchema;
+};
+type EntityActorKey<Machines extends MachineStore> = {
+    readonly [Key in keyof Machines]: Machines[Key] extends EntityActorMachine ? Key : never;
+}[keyof Machines] & string;
+type EntityActorSpawnSchema<Machines extends MachineStore, Key extends EntityActorKey<Machines>> = Machines[Key] extends {
+    readonly spawnSchema: infer SpawnSchema extends EntitySpawnSchema;
+} ? SpawnSchema : never;
+type EntitySpawnActors<Machines extends MachineStore> = Partial<{
+    readonly [Key in EntityActorKey<Machines>]: EntitySpawnPayload<EntityActorSpawnSchema<Machines, Key>>;
+}>;
+export type EntitySpawnSpec<Machines extends MachineStore = MachineStore> = {
+    readonly id: string;
+    readonly groupTag: string;
+    readonly actors: EntitySpawnActors<Machines>;
+};
+type EntitySpawnRecipeResult<Machines extends MachineStore> = EntitySpawnSpec<Machines> | readonly EntitySpawnSpec<Machines>[];
+export type EntitySpawnRecipes<Machines extends MachineStore, SpawnEvents extends SpawnEventsConfig> = {
+    readonly [Type in keyof SpawnEvents & string]: (payload: SpawnEventPayload<SpawnEvents[Type]>) => EntitySpawnRecipeResult<Machines>;
+};
+export type EntitySpawnDescriptor<SpawnEvents extends SpawnEventsConfig = SpawnEventsConfig, Machines extends MachineStore = MachineStore> = {
+    readonly [entitySpawnMarker]: true;
+    readonly spawnEvents: SpawnEvents;
+    readonly recipes: EntitySpawnRecipes<Machines, SpawnEvents>;
+};
+export type EntitySpawnEvents<Spawn> = Spawn extends EntitySpawnDescriptor<infer SpawnEvents, any> ? SpawnEvents : never;
+export type EntitySpawnPluginEvents<Spawn> = SpawnEventsFrom<EntitySpawnEvents<Spawn>>;
+export type AnyEntitySpawnDescriptor = EntitySpawnDescriptor<any, any>;
+export declare const spawnEvent: <Payload>() => SpawnEventDescriptor<Payload>;
+export declare const defineSpawnEvents: <const SpawnEvents extends SpawnEventsConfig>(events: SpawnEvents) => SpawnEvents;
+export declare const defineEntitySpawn: <const Machines extends MachineStore, const SpawnEvents extends SpawnEventsConfig>(_machines: Machines, spawnEvents: SpawnEvents) => (recipes: EntitySpawnRecipes<Machines, SpawnEvents>) => EntitySpawnDescriptor<SpawnEvents, Machines>;
+export declare const isEntitySpawnDescriptor: (value: unknown) => value is AnyEntitySpawnDescriptor;
+export declare function assertEntitySpawnDescriptor(value: unknown): asserts value is AnyEntitySpawnDescriptor;
+export declare const hasSpawnRecipe: (spawn: AnyEntitySpawnDescriptor, type: string) => boolean;
+export declare const runSpawnRecipe: (spawn: AnyEntitySpawnDescriptor, action: AnyEvent) => EntitySpawnRecipeResult<MachineStore>;
+export {};

package/dist/spawn.d.ts

@@ -0,0 +1,56 @@
+import type { AnyEvent, MachineStore } from "@lite-fsm/core";
+import type { EntitySpawnPayload, EntitySpawnSchema } from "./schema";
+declare const spawnEventMarker: unique symbol;
+declare const entitySpawnMarker: unique symbol;
+export type SpawnEventDescriptor<Payload> = {
+    readonly [spawnEventMarker]: true;
+    readonly payloadType?: Payload;
+};
+type SpawnEventPayload<Descriptor> = Descriptor extends {
+    readonly payloadType?: infer Payload;
+} ? Payload : never;
+export type SpawnEventsConfig = Readonly<Record<string, SpawnEventDescriptor<unknown>>>;
+export type SpawnEventsFrom<SpawnEvents extends SpawnEventsConfig> = {
+    readonly [Type in keyof SpawnEvents & string]: {
+        readonly type: Type;
+        readonly payload: SpawnEventPayload<SpawnEvents[Type]>;
+    };
+}[keyof SpawnEvents & string];
+type EntityActorMachine = {
+    readonly storage: "entity";
+    readonly spawnSchema: EntitySpawnSchema;
+};
+type EntityActorKey<Machines extends MachineStore> = {
+    readonly [Key in keyof Machines]: Machines[Key] extends EntityActorMachine ? Key : never;
+}[keyof Machines] & string;
+type EntityActorSpawnSchema<Machines extends MachineStore, Key extends EntityActorKey<Machines>> = Machines[Key] extends {
+    readonly spawnSchema: infer SpawnSchema extends EntitySpawnSchema;
+} ? SpawnSchema : never;
+type EntitySpawnActors<Machines extends MachineStore> = Partial<{
+    readonly [Key in EntityActorKey<Machines>]: EntitySpawnPayload<EntityActorSpawnSchema<Machines, Key>>;
+}>;
+export type EntitySpawnSpec<Machines extends MachineStore = MachineStore> = {
+    readonly id: string;
+    readonly groupTag: string;
+    readonly actors: EntitySpawnActors<Machines>;
+};
+type EntitySpawnRecipeResult<Machines extends MachineStore> = EntitySpawnSpec<Machines> | readonly EntitySpawnSpec<Machines>[];
+export type EntitySpawnRecipes<Machines extends MachineStore, SpawnEvents extends SpawnEventsConfig> = {
+    readonly [Type in keyof SpawnEvents & string]: (payload: SpawnEventPayload<SpawnEvents[Type]>) => EntitySpawnRecipeResult<Machines>;
+};
+export type EntitySpawnDescriptor<SpawnEvents extends SpawnEventsConfig = SpawnEventsConfig, Machines extends MachineStore = MachineStore> = {
+    readonly [entitySpawnMarker]: true;
+    readonly spawnEvents: SpawnEvents;
+    readonly recipes: EntitySpawnRecipes<Machines, SpawnEvents>;
+};
+export type EntitySpawnEvents<Spawn> = Spawn extends EntitySpawnDescriptor<infer SpawnEvents, any> ? SpawnEvents : never;
+export type EntitySpawnPluginEvents<Spawn> = SpawnEventsFrom<EntitySpawnEvents<Spawn>>;
+export type AnyEntitySpawnDescriptor = EntitySpawnDescriptor<any, any>;
+export declare const spawnEvent: <Payload>() => SpawnEventDescriptor<Payload>;
+export declare const defineSpawnEvents: <const SpawnEvents extends SpawnEventsConfig>(events: SpawnEvents) => SpawnEvents;
+export declare const defineEntitySpawn: <const Machines extends MachineStore, const SpawnEvents extends SpawnEventsConfig>(_machines: Machines, spawnEvents: SpawnEvents) => (recipes: EntitySpawnRecipes<Machines, SpawnEvents>) => EntitySpawnDescriptor<SpawnEvents, Machines>;
+export declare const isEntitySpawnDescriptor: (value: unknown) => value is AnyEntitySpawnDescriptor;
+export declare function assertEntitySpawnDescriptor(value: unknown): asserts value is AnyEntitySpawnDescriptor;
+export declare const hasSpawnRecipe: (spawn: AnyEntitySpawnDescriptor, type: string) => boolean;
+export declare const runSpawnRecipe: (spawn: AnyEntitySpawnDescriptor, action: AnyEvent) => EntitySpawnRecipeResult<MachineStore>;
+export {};