@blibliki/engine 0.3.7 → 0.3.8

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { Context, Optional, EmptyObject } from '@blibliki/utils';
 export { Context } from '@blibliki/utils';
 import { Message, Input } from 'webmidi';
 import * as _blibliki_transport from '@blibliki/transport';
-import { Seconds, ContextTime, Transport, TransportEvent, TimeSignature } from '@blibliki/transport';
+import { Seconds, ContextTime, Transport, TransportEvent, BPM, TimeSignature } from '@blibliki/transport';
 export { Position, TimeSignature, TransportState } from '@blibliki/transport';
 
 type INote = {
@@ -109,6 +109,65 @@ declare class ComputerKeyboardInput implements IMidiInput {
     private extractNote;
 }
 
+type MidiInputProps = IOProps & {
+    ioType: IOType.MidiInput;
+    onMidiEvent: (event: MidiEvent) => void;
+};
+type MidiOutputProps = IOProps & {
+    ioType: IOType.MidiOutput;
+};
+declare class MidiInput extends IO<MidiOutput> implements MidiInputProps {
+    ioType: IOType.MidiInput;
+    onMidiEvent: MidiInputProps["onMidiEvent"];
+    constructor(module: Module<ModuleType> | PolyModule<ModuleType>, props: MidiInputProps);
+}
+declare class MidiOutput extends IO<MidiInput> implements MidiOutputProps {
+    ioType: IOType.MidiOutput;
+    onMidiEvent: (event: MidiEvent) => void;
+    private get midiConnections();
+}
+
+type IOProps = {
+    name: string;
+    ioType: IOType;
+};
+type IIOSerialize = IOProps & {
+    id: string;
+    moduleId: string;
+};
+declare enum IOType {
+    AudioInput = "audioInput",
+    AudioOutput = "audioOutput",
+    PolyAudioInput = "polyAudioInput",
+    PolyAudioOutput = "polyAudioOutput",
+    MidiOutput = "midiOutput",
+    MidiInput = "midiInput"
+}
+type IIO = {
+    id: string;
+    module: Module<ModuleType> | PolyModule<ModuleType>;
+} & IOProps;
+declare abstract class Base implements IIO {
+    id: string;
+    ioType: IOType;
+    name: string;
+    module: Module<ModuleType> | PolyModule<ModuleType>;
+    connections: Base[];
+    constructor(module: Module<ModuleType> | PolyModule<ModuleType>, props: IOProps);
+    plug(io: Base, plugOther?: boolean): void;
+    unPlug(io: Base, plugOther?: boolean): void;
+    rePlugAll(callback?: () => void): void;
+    unPlugAll(): void;
+    isAudio(): this is AudioInput | AudioOutput | PolyAudioInput | PolyAudioOutput;
+    isMidi(): this is MidiInput | MidiOutput;
+    serialize(): IIOSerialize;
+}
+declare abstract class IO<Connection extends Base> extends Base {
+    connections: Connection[];
+    plug(io: Connection, plugOther?: boolean): void;
+    unPlug(io: Connection, plugOther?: boolean): void;
+}
+
 type AudioInputProps = IOProps & {
     ioType: IOType.AudioInput;
     getAudioNode: () => AudioNode | AudioParam | AudioDestinationNode;
@@ -151,79 +210,6 @@ declare class PolyAudioOutput extends IO<PolyAudioInput | AudioInput> implements
     findIOByVoice(voice: number): AudioOutput;
 }
 
-type IPolyModule<T extends ModuleType> = Omit<IModule<T>, "voiceNo"> & {
-    voices: number;
-};
-type IPolyModuleSerialize<T extends ModuleType> = IPolyModule<T> & {
-    inputs: IIOSerialize[];
-    outputs: IIOSerialize[];
-};
-type IPolyModuleConstructor<T extends ModuleType> = Optional<IPolyModule<T>, "id"> & {
-    monoModuleConstructor: (engineId: string, params: IModuleConstructor<T>) => Module<T>;
-};
-declare abstract class PolyModule<T extends ModuleType> implements IPolyModule<T> {
-    id: string;
-    engineId: string;
-    moduleType: T;
-    audioModules: Module<T>[];
-    inputs: InputCollection;
-    outputs: OutputCollection;
-    protected monoModuleConstructor: IPolyModuleConstructor<T>["monoModuleConstructor"];
-    protected _props: ModuleTypeToPropsMapping[T];
-    protected superInitialized: boolean;
-    private _voices;
-    private _name;
-    private pendingUIUpdates;
-    constructor(engineId: string, params: IPolyModuleConstructor<T>);
-    get name(): string;
-    set name(value: string);
-    get props(): ModuleTypeToPropsMapping[T];
-    set props(value: Partial<ModuleTypeToPropsMapping[T]>);
-    get voices(): number;
-    set voices(value: number);
-    start(time: ContextTime): void;
-    stop(time: ContextTime): void;
-    serialize(): IPolyModuleSerialize<T>;
-    plug({ audioModule, from, to, }: {
-        audioModule: Module<ModuleType> | PolyModule<ModuleType>;
-        from: string;
-        to: string;
-    }): void;
-    rePlugAll(callback?: () => void): void;
-    protected unPlugAll(): void;
-    dispose(): void;
-    onMidiEvent: (midiEvent: MidiEvent) => void;
-    triggerPropsUpdate: () => void;
-    private sheduleTriggerUpdate;
-    findVoice(voiceNo: number): Module<T>;
-    protected registerDefaultIOs(value?: "both" | "in" | "out"): void;
-    protected registerAudioInput(props: Omit<PolyAudioInputProps, "ioType">): PolyAudioInput;
-    protected registerAudioOutput(props: Omit<PolyAudioOutputProps, "ioType">): PolyAudioOutput;
-    protected registerMidiInput(props: Omit<MidiInputProps, "ioType">): MidiInput;
-    protected registerMidiOutput(props: Omit<MidiOutputProps, "ioType">): MidiOutput;
-    private adjustNumberOfModules;
-    protected get engine(): Engine;
-    protected get context(): _blibliki_utils.Context;
-}
-
-type MidiInputProps = IOProps & {
-    ioType: IOType.MidiInput;
-    onMidiEvent: (event: MidiEvent) => void;
-};
-type MidiOutputProps = IOProps & {
-    ioType: IOType.MidiOutput;
-};
-declare class MidiInput extends IO<MidiOutput> implements MidiInputProps {
-    ioType: IOType.MidiInput;
-    onMidiEvent: MidiInputProps["onMidiEvent"];
-    constructor(module: Module<ModuleType> | PolyModule<ModuleType>, props: MidiInputProps);
-}
-declare class MidiOutput extends IO<MidiInput> implements MidiOutputProps {
-    ioType: IOType.MidiOutput;
-    onMidiEvent: (event: MidiEvent) => void;
-    private get midiConnections();
-}
-
 declare enum CollectionType {
     Input = "Input",
     Output = "Output"
@@ -260,138 +246,58 @@ declare class OutputCollection extends IOCollection<CollectionType.Output> {
     constructor(module: Module<ModuleType> | PolyModule<ModuleType>);
 }
 
-type IModule<T extends ModuleType> = {
-    id: string;
-    name: string;
-    voiceNo: number;
-    moduleType: T;
-    props: ModuleTypeToPropsMapping[T];
+type IPolyModule<T extends ModuleType> = Omit<IModule<T>, "voiceNo"> & {
+    voices: number;
 };
-type IModuleSerialize<T extends ModuleType> = IModule<T> & {
+type IPolyModuleSerialize<T extends ModuleType> = IPolyModule<T> & {
     inputs: IIOSerialize[];
     outputs: IIOSerialize[];
 };
-type IModuleConstructor<T extends ModuleType> = Optional<IModule<T>, "id" | "voiceNo"> & {
-    audioNodeConstructor?: (context: Context) => AudioNode;
-};
-/**
- * Helper type for type-safe property lifecycle hooks.
- *
- * Hooks are completely optional - only define the ones you need.
- * Use explicit type annotation for automatic type inference.
- *
- * @example
- * ```typescript
- * export type IGainProps = {
- *   gain: number;
- *   muted: boolean;
- * };
- *
- * export class MonoGain extends Module<ModuleType.Gain> {
- *   // ✅ Define only the hooks you need with type annotation
- *   // value type is automatically inferred as number!
- *   onSetGain: SetterHooks<IGainProps>["onSetGain"] = (value) => {
- *     this.audioNode.gain.value = value;
- *     return value; // optional: return modified value
- *   };
- *
- *   // ✅ onAfterSet is called after prop is set
- *   onAfterSetMuted: SetterHooks<IGainProps>["onAfterSetMuted"] = (value) => {
- *     if (value) this.audioNode.gain.value = 0;
- *   };
- *
- *   // ✅ You can omit hooks you don't need - they're optional!
- *   // No need to define onSetMuted if you don't need it
- *
- *   // ❌ This would cause a type error:
- *   // onSetGain: SetterHooks<IGainProps>["onSetGain"] = (value: string) => value;
- *   //                                                            ^^^^^^ Error!
- * }
- * ```
- */
-type SetterHooks<P> = {
-    [K in keyof P as `onSet${Capitalize<string & K>}`]: (value: P[K]) => P[K];
-} & {
-    [K in keyof P as `onAfterSet${Capitalize<string & K>}`]: (value: P[K]) => void;
+type IPolyModuleConstructor<T extends ModuleType> = Optional<IPolyModule<T>, "id"> & {
+    monoModuleConstructor: (engineId: string, params: IModuleConstructor<T>) => Module<T>;
 };
-declare abstract class Module<T extends ModuleType> implements IModule<T> {
+declare abstract class PolyModule<T extends ModuleType> implements IPolyModule<T> {
     id: string;
     engineId: string;
-    name: string;
     moduleType: T;
-    voiceNo: number;
-    audioNode: AudioNode | undefined;
+    audioModules: Module<T>[];
     inputs: InputCollection;
     outputs: OutputCollection;
+    protected monoModuleConstructor: IPolyModuleConstructor<T>["monoModuleConstructor"];
     protected _props: ModuleTypeToPropsMapping[T];
-    protected superInitialized: boolean;
-    protected activeNotes: Note[];
+    private _voices;
+    private _name;
     private pendingUIUpdates;
-    constructor(engineId: string, params: IModuleConstructor<T>);
+    constructor(engineId: string, params: IPolyModuleConstructor<T>);
+    get name(): string;
+    set name(value: string);
     get props(): ModuleTypeToPropsMapping[T];
     set props(value: Partial<ModuleTypeToPropsMapping[T]>);
-    private callPropHook;
-    serialize(): IModuleSerialize<T>;
+    get voices(): number;
+    set voices(value: number);
+    start(time: ContextTime): void;
+    stop(time: ContextTime): void;
+    serialize(): IPolyModuleSerialize<T>;
     plug({ audioModule, from, to, }: {
-        audioModule: AnyModule;
+        audioModule: Module<ModuleType> | PolyModule<ModuleType>;
         from: string;
         to: string;
     }): void;
-    protected rePlugAll(callback?: () => void): void;
+    rePlugAll(callback?: () => void): void;
     protected unPlugAll(): void;
-    start(_time: ContextTime): void;
-    stop(_time: ContextTime): void;
-    triggerAttack(note: Note, _triggeredAt: ContextTime): void;
-    triggerRelease(note: Note, _triggeredAt: ContextTime): void;
-    handleCC(_event: MidiEvent, _triggeredAt: ContextTime): void;
+    dispose(): void;
     onMidiEvent: (midiEvent: MidiEvent) => void;
     triggerPropsUpdate: () => void;
     private sheduleTriggerUpdate;
-    dispose(): void;
+    findVoice(voiceNo: number): Module<T>;
     protected registerDefaultIOs(value?: "both" | "in" | "out"): void;
-    protected registerAudioInput(props: Omit<AudioInputProps, "ioType">): AudioInput;
-    protected registerAudioOutput(props: Omit<AudioOutputProps, "ioType">): AudioOutput;
+    protected registerAudioInput(props: Omit<PolyAudioInputProps, "ioType">): PolyAudioInput;
+    protected registerAudioOutput(props: Omit<PolyAudioOutputProps, "ioType">): PolyAudioOutput;
     protected registerMidiInput(props: Omit<MidiInputProps, "ioType">): MidiInput;
     protected registerMidiOutput(props: Omit<MidiOutputProps, "ioType">): MidiOutput;
+    private adjustNumberOfModules;
     protected get engine(): Engine;
-    protected get context(): Context;
-}
-
-type IPlug = {
-    moduleId: string;
-    ioName: string;
-};
-type IRoute = {
-    id: string;
-    source: IPlug;
-    destination: IPlug;
-};
-declare class Routes {
-    engine: Engine;
-    routes: Map<string, IRoute>;
-    constructor(engine: Engine);
-    addRoute(props: Optional<IRoute, "id">): IRoute;
-    removeRoute(id: string): void;
-    clear(): void;
-    private plug;
-    private unPlug;
-    private find;
-    private getIOs;
-}
-
-type ListenerCallback = (device: MidiDevice) => void;
-declare class MidiDeviceManager {
-    devices: Map<string, MidiDevice | ComputerKeyboardInput>;
-    private initialized;
-    private listeners;
-    private context;
-    constructor(context: Context);
-    initialize(): Promise<void>;
-    find(id: string): MidiDevice | ComputerKeyboardInput | undefined;
-    addListener(callback: ListenerCallback): void;
-    private initializeDevices;
-    private addComputerKeyboard;
-    private listenChanges;
+    protected get context(): _blibliki_utils.Context;
 }
 
 type BasePropType = {
@@ -605,6 +511,7 @@ declare class MidiMapper extends Module<ModuleType.MidiMapper> implements MidiMa
 
 type IMidiSelectorProps = {
     selectedId: string | undefined | null;
+    selectedName: string | undefined | null;
 };
 declare class MidiSelector extends Module<ModuleType.MidiSelector> implements Pick<SetterHooks<IMidiSelectorProps>, "onSetSelectedId"> {
     audioNode: undefined;
@@ -755,45 +662,105 @@ type ModuleParams = {
     [K in ModuleType]: K extends ModuleType.Oscillator | ModuleType.Gain | ModuleType.Envelope | ModuleType.Filter | ModuleType.StereoPanner | ModuleType.VoiceScheduler ? IPolyModuleConstructor<K> : ICreateModule<K>;
 }[ModuleType];
 
-type IOProps = {
+type IModule<T extends ModuleType> = {
+    id: string;
     name: string;
-    ioType: IOType;
+    voiceNo: number;
+    moduleType: T;
+    props: ModuleTypeToPropsMapping[T];
 };
-type IIOSerialize = IOProps & {
+type IModuleSerialize<T extends ModuleType> = IModule<T> & {
+    inputs: IIOSerialize[];
+    outputs: IIOSerialize[];
+};
+type IModuleConstructor<T extends ModuleType> = Optional<IModule<T>, "id" | "voiceNo"> & {
+    audioNodeConstructor?: (context: Context) => AudioNode;
+};
+type SetterHooks<P> = {
+    [K in keyof P as `onSet${Capitalize<string & K>}`]: (value: P[K]) => P[K];
+} & {
+    [K in keyof P as `onAfterSet${Capitalize<string & K>}`]: (value: P[K]) => void;
+};
+declare abstract class Module<T extends ModuleType> implements IModule<T> {
     id: string;
+    engineId: string;
+    name: string;
+    moduleType: T;
+    voiceNo: number;
+    audioNode: AudioNode | undefined;
+    inputs: InputCollection;
+    outputs: OutputCollection;
+    protected _props: ModuleTypeToPropsMapping[T];
+    protected activeNotes: Note[];
+    private pendingUIUpdates;
+    constructor(engineId: string, params: IModuleConstructor<T>);
+    get props(): ModuleTypeToPropsMapping[T];
+    set props(value: Partial<ModuleTypeToPropsMapping[T]>);
+    private callPropHook;
+    serialize(): IModuleSerialize<T>;
+    plug({ audioModule, from, to, }: {
+        audioModule: AnyModule;
+        from: string;
+        to: string;
+    }): void;
+    protected rePlugAll(callback?: () => void): void;
+    protected unPlugAll(): void;
+    start(_time: ContextTime): void;
+    stop(_time: ContextTime): void;
+    triggerAttack(note: Note, _triggeredAt: ContextTime): void;
+    triggerRelease(note: Note, _triggeredAt: ContextTime): void;
+    handleCC(_event: MidiEvent, _triggeredAt: ContextTime): void;
+    onMidiEvent: (midiEvent: MidiEvent) => void;
+    triggerPropsUpdate: () => void;
+    private sheduleTriggerUpdate;
+    dispose(): void;
+    protected registerDefaultIOs(value?: "both" | "in" | "out"): void;
+    protected registerAudioInput(props: Omit<AudioInputProps, "ioType">): AudioInput;
+    protected registerAudioOutput(props: Omit<AudioOutputProps, "ioType">): AudioOutput;
+    protected registerMidiInput(props: Omit<MidiInputProps, "ioType">): MidiInput;
+    protected registerMidiOutput(props: Omit<MidiOutputProps, "ioType">): MidiOutput;
+    protected get engine(): Engine;
+    protected get context(): Context;
+}
+
+type IPlug = {
     moduleId: string;
+    ioName: string;
 };
-declare enum IOType {
-    AudioInput = "audioInput",
-    AudioOutput = "audioOutput",
-    PolyAudioInput = "polyAudioInput",
-    PolyAudioOutput = "polyAudioOutput",
-    MidiOutput = "midiOutput",
-    MidiInput = "midiInput"
-}
-type IIO = {
-    id: string;
-    module: Module<ModuleType> | PolyModule<ModuleType>;
-} & IOProps;
-declare abstract class Base implements IIO {
+type IRoute = {
     id: string;
-    ioType: IOType;
-    name: string;
-    module: Module<ModuleType> | PolyModule<ModuleType>;
-    connections: Base[];
-    constructor(module: Module<ModuleType> | PolyModule<ModuleType>, props: IOProps);
-    plug(io: Base, plugOther?: boolean): void;
-    unPlug(io: Base, plugOther?: boolean): void;
-    rePlugAll(callback?: () => void): void;
-    unPlugAll(): void;
-    isAudio(): this is AudioInput | AudioOutput | PolyAudioInput | PolyAudioOutput;
-    isMidi(): this is MidiInput | MidiOutput;
-    serialize(): IIOSerialize;
+    source: IPlug;
+    destination: IPlug;
+};
+declare class Routes {
+    engine: Engine;
+    routes: Map<string, IRoute>;
+    constructor(engine: Engine);
+    addRoute(props: Optional<IRoute, "id">): IRoute;
+    removeRoute(id: string): void;
+    clear(): void;
+    replug(): void;
+    serialize(): IRoute[];
+    private plug;
+    private unPlug;
+    private find;
+    private getIOs;
 }
-declare abstract class IO<Connection extends Base> extends Base {
-    connections: Connection[];
-    plug(io: Connection, plugOther?: boolean): void;
-    unPlug(io: Connection, plugOther?: boolean): void;
+
+type ListenerCallback = (device: MidiDevice) => void;
+declare class MidiDeviceManager {
+    devices: Map<string, MidiDevice | ComputerKeyboardInput>;
+    private initialized;
+    private listeners;
+    private context;
+    constructor(context: Context);
+    initialize(): Promise<void>;
+    find(id: string): MidiDevice | ComputerKeyboardInput | undefined;
+    findByName(name: string): MidiDevice | ComputerKeyboardInput | undefined;
+    addListener(callback: ListenerCallback): void;
+    private initializeDevices;
+    private addComputerKeyboard;
+    private listenChanges;
 }
 
 type IUpdateModule<T extends ModuleType> = {
@@ -804,6 +771,12 @@ type IUpdateModule<T extends ModuleType> = {
     };
 };
 type ICreateRoute = Optional<IRoute, "id">;
+interface IEngineSerialize {
+    bpm: BPM;
+    timeSignature: TimeSignature;
+    modules: (IModuleSerialize<ModuleType> | IPolyModuleSerialize<ModuleType>)[];
+    routes: IRoute[];
+}
 declare class Engine {
     private static _engines;
     private static _currentId;
@@ -817,6 +790,7 @@ declare class Engine {
     midiDeviceManager: MidiDeviceManager;
     static getById(id: string): Engine;
     static get current(): Engine;
+    static load(data: IEngineSerialize): Promise<Engine>;
     constructor(context: Context);
     get state(): _blibliki_transport.TransportState;
     initialize(): Promise<void>;
@@ -835,9 +809,11 @@ declare class Engine {
     set timeSignature(value: TimeSignature);
     resume(): Promise<void>;
     dispose(): void;
+    serialize(): IEngineSerialize;
     findModule(id: string): ModuleTypeToModuleMapping[keyof ModuleTypeToModuleMapping];
     findIO(moduleId: string, ioName: string, type: "input" | "output"): Base;
     findMidiDevice(id: string): MidiDevice | ComputerKeyboardInput | undefined;
+    findMidiDeviceByName(name: string): MidiDevice | ComputerKeyboardInput | undefined;
     onPropsUpdate(callback: <T extends ModuleType>(params: IModule<T> | IPolyModule<T>) => void): void;
     _triggerPropsUpdate<T extends ModuleType>(params: IModule<T> | IPolyModule<T>): void;
     triggerVirtualMidi(id: string, noteName: string, type: "noteOn" | "noteOff"): void;
@@ -845,4 +821,4 @@ declare class Engine {
     private onStop;
 }
 
-export { type ArrayProp, type BooleanProp, Engine, type EnumProp, type ICreateModule, type ICreateRoute, type IGain, type IIOSerialize, type IMaster, type IMidiDevice, type IMidiMapper, type IMidiMapperProps, type IModule, type IModuleSerialize, type INote, type IOscillator, type IPolyModuleSerialize, type IRoute, type ISequence, type IStepSequencer, type IStepSequencerProps, type IUpdateModule, MidiDevice, type MidiMapping, MidiMappingMode, MidiPortState, type ModuleParams, type ModulePropSchema, ModuleType, type ModuleTypeToPropsMapping, Note, type NumberProp, OscillatorWave, type PropSchema, type StringProp, moduleSchemas };
+export { type ArrayProp, type BooleanProp, Engine, type EnumProp, type ICreateModule, type ICreateRoute, type IEngineSerialize, type IGain, type IIOSerialize, type IMaster, type IMidiDevice, type IMidiMapper, type IMidiMapperProps, type IModule, type IModuleSerialize, type INote, type IOscillator, type IPolyModuleSerialize, type IRoute, type ISequence, type IStepSequencer, type IStepSequencerProps, type IUpdateModule, MidiDevice, type MidiMapping, MidiMappingMode, MidiPortState, type ModuleParams, type ModulePropSchema, ModuleType, type ModuleTypeToPropsMapping, Note, type NumberProp, OscillatorWave, type PropSchema, type StringProp, moduleSchemas };