@blibliki/engine 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blibliki/engine",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "source": "src/index.ts",
   "main": "dist/index.cjs",
@@ -12,16 +12,16 @@
     "dist"
   ],
   "devDependencies": {
-    "@types/audioworklet": "^0.0.87",
+    "@types/audioworklet": "^0.0.91",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.0.7"
+    "vitest": "^4.0.6"
   },
   "dependencies": {
-    "@ircam/sc-scheduling": "^1.0.0",
+    "es-toolkit": "^1.41.0",
     "node-web-audio-api": "^1.0.3",
     "webmidi": "^3.1.14",
-    "@blibliki/transport": "^0.3.4",
-    "@blibliki/utils": "^0.3.4"
+    "@blibliki/transport": "^0.3.7",
+    "@blibliki/utils": "^0.3.7"
   },
   "scripts": {
     "build": "tsup",

package/src/Engine.ts

@@ -20,7 +20,7 @@ import {
   ModuleTypeToModuleMapping,
   createModule,
 } from "@/modules";
-import { PolyModule } from "./core/module/PolyModule";
+import { IPolyModule, PolyModule } from "./core/module/PolyModule";
 import { loadProcessors } from "./processors";
 
 export type IUpdateModule<T extends ModuleType> = {
@@ -37,7 +37,7 @@ export class Engine {
   private static _engines = new Map<string, Engine>();
   private static _currentId: string | undefined;
   private propsUpdateCallbacks: (<T extends ModuleType>(
-    params: IModule<T>,
+    params: IModule<T> | IPolyModule<T>,
   ) => void)[] = [];
 
   readonly id: string;
@@ -219,11 +219,17 @@ export class Engine {
     return this.midiDeviceManager.find(id);
   }
 
-  onPropsUpdate(callback: <T extends ModuleType>(params: IModule<T>) => void) {
+  onPropsUpdate(
+    callback: <T extends ModuleType>(
+      params: IModule<T> | IPolyModule<T>,
+    ) => void,
+  ) {
     this.propsUpdateCallbacks.push(callback);
   }
 
-  _triggerPropsUpdate<T extends ModuleType>(params: IModule<T>) {
+  _triggerPropsUpdate<T extends ModuleType>(
+    params: IModule<T> | IPolyModule<T>,
+  ) {
     this.propsUpdateCallbacks.forEach((callback) => {
       callback(params);
     });

package/src/core/IO/Collection.ts

@@ -1,4 +1,5 @@
 import { assertNever } from "@blibliki/utils";
+import { sortBy } from "es-toolkit";
 import { ModuleType } from "@/modules";
 import { Module } from "../module";
 import { PolyModule } from "../module/PolyModule";
@@ -129,7 +130,9 @@ export default abstract class IOCollection<T extends CollectionType> {
   }
 
   serialize() {
-    return this.collection.map((io) => io.serialize());
+    return sortBy(this.collection, [(io) => (io.isMidi() ? -1 : 1)]).map((io) =>
+      io.serialize(),
+    );
   }
 
   private validateUniqName(name: string) {

package/src/core/index.ts

@@ -1,5 +1,10 @@
 export { Module } from "./module";
-export type { IModule, IModuleSerialize, IPolyModuleSerialize } from "./module";
+export type {
+  IModule,
+  IModuleSerialize,
+  IPolyModuleSerialize,
+  SetterHooks,
+} from "./module";
 
 export type IAnyAudioContext = AudioContext | OfflineAudioContext;
 
@@ -20,7 +25,7 @@ export type {
 } from "./IO";
 
 export type {
-  PropDefinition,
+  ModulePropSchema,
   PropSchema,
   NumberProp,
   StringProp,

package/src/core/midi/MidiDevice.ts

@@ -75,6 +75,7 @@ export default class MidiDevice implements IMidiDevice {
     switch (midiEvent.type) {
       case MidiEventType.noteOn:
       case MidiEventType.noteOff:
+      case MidiEventType.cc:
         this.eventListerCallbacks.forEach((callback) => {
           callback(midiEvent);
         });

package/src/core/midi/MidiEvent.ts

@@ -5,7 +5,7 @@ import Note, { INote } from "../Note";
 export enum MidiEventType {
   noteOn = "noteon",
   noteOff = "noteoff",
-  cc = "cc",
+  cc = "controlchange",
 }
 
 export default class MidiEvent {
@@ -51,6 +51,22 @@ export default class MidiEvent {
     );
   }
 
+  get isCC() {
+    return this.type === MidiEventType.cc;
+  }
+
+  get cc(): number | undefined {
+    if (!this.isCC) return;
+
+    return this.message.dataBytes[0];
+  }
+
+  get ccValue(): number | undefined {
+    if (!this.isCC) return;
+
+    return this.message.dataBytes[1];
+  }
+
   defineNotes() {
     if (!this.isNote) return;
     if (this.note) return;

package/src/core/module/Module.ts

@@ -35,6 +35,49 @@ export type IModuleConstructor<T extends ModuleType> = Optional<
   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!
+ * }
+ * ```
+ */
+export 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;
+};
+
 export abstract class Module<T extends ModuleType> implements IModule<T> {
   id: string;
   engineId: string;
@@ -47,6 +90,7 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
   protected _props!: ModuleTypeToPropsMapping[T];
   protected superInitialized = false;
   protected activeNotes: Note[];
+  private pendingUIUpdates = false;
 
   constructor(engineId: string, params: IModuleConstructor<T>) {
     const { id, name, moduleType, voiceNo, audioNodeConstructor, props } =
@@ -59,13 +103,17 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
     this.voiceNo = voiceNo ?? 0;
     this.activeNotes = [];
     this.audioNode = audioNodeConstructor?.(this.context);
-    this._props = {} as ModuleTypeToPropsMapping[T];
-    this.props = props;
+    this._props = props;
 
     this.inputs = new InputCollection(this);
     this.outputs = new OutputCollection(this);
 
     this.superInitialized = true;
+
+    // Defer hook calls until after subclass is fully initialized
+    queueMicrotask(() => {
+      this.props = props;
+    });
   }
 
   get props(): ModuleTypeToPropsMapping[T] {
@@ -73,25 +121,51 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
   }
 
   set props(value: Partial<ModuleTypeToPropsMapping[T]>) {
-    Object.keys(value).forEach((key) => {
-      const onSetAttr = `onSet${upperFirst(key)}`;
-
-      // @ts-expect-error TS7053 ignore this error
-      // eslint-disable-next-line
-      this[onSetAttr]?.(value[key]);
-    });
-
-    this._props = { ...this._props, ...value };
+    const updatedValue = { ...value };
+
+    (Object.keys(value) as (keyof ModuleTypeToPropsMapping[T])[]).forEach(
+      (key) => {
+        const propValue = value[key];
+        if (propValue !== undefined) {
+          const result = this.callPropHook("onSet", key, propValue);
+          if (result !== undefined) {
+            updatedValue[key] = result;
+          }
+        }
+      },
+    );
 
-    Object.keys(value).forEach((key) => {
-      const onSetAttr = `onAfterSet${upperFirst(key)}`;
+    this._props = { ...this._props, ...updatedValue };
 
-      // @ts-expect-error TS7053 ignore this error
-      // eslint-disable-next-line
-      this[onSetAttr]?.(value[key]);
+    (
+      Object.keys(updatedValue) as (keyof ModuleTypeToPropsMapping[T])[]
+    ).forEach((key) => {
+      const propValue = updatedValue[key];
+      if (propValue !== undefined) {
+        this.callPropHook("onAfterSet", key, propValue);
+      }
     });
   }
 
+  private callPropHook<K extends keyof ModuleTypeToPropsMapping[T]>(
+    hookType: "onSet" | "onAfterSet",
+    key: K,
+    value: ModuleTypeToPropsMapping[T][K],
+  ): ModuleTypeToPropsMapping[T][K] | undefined {
+    const hookName = `${hookType}${upperFirst(key as string)}`;
+    const hook = this[hookName as keyof this];
+
+    if (typeof hook === "function") {
+      const result = (
+        hook as (
+          value: ModuleTypeToPropsMapping[T][K],
+        ) => ModuleTypeToPropsMapping[T][K] | undefined
+      ).call(this, value);
+      return result;
+    }
+    return undefined;
+  }
+
   serialize(): IModuleSerialize<T> {
     return {
       id: this.id,
@@ -149,6 +223,10 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
     );
   }
 
+  handleCC(_event: MidiEvent, _triggeredAt: ContextTime): void {
+    // Optional implementation in modules
+  }
+
   onMidiEvent = (midiEvent: MidiEvent) => {
     const { note, triggeredAt } = midiEvent;
 
@@ -160,18 +238,31 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
       case MidiEventType.noteOff:
         this.triggerRelease(note!, triggeredAt);
         break;
+      case MidiEventType.cc:
+        this.handleCC(midiEvent, triggeredAt);
+        break;
       default:
         throw Error("This type is not a note");
     }
   };
 
-  protected triggerPropsUpdate() {
-    this.engine._triggerPropsUpdate({
-      id: this.id,
-      moduleType: this.moduleType,
-      voiceNo: this.voiceNo,
-      name: this.name,
-      props: this.props,
+  triggerPropsUpdate = () => {
+    if (this.pendingUIUpdates) return;
+
+    this.pendingUIUpdates = true;
+    this.sheduleTriggerUpdate();
+  };
+
+  private sheduleTriggerUpdate() {
+    requestAnimationFrame(() => {
+      this.engine._triggerPropsUpdate({
+        id: this.id,
+        moduleType: this.moduleType,
+        voiceNo: this.voiceNo,
+        name: this.name,
+        props: this.props,
+      });
+      this.pendingUIUpdates = false;
     });
   }
 

package/src/core/module/PolyModule.ts

@@ -47,6 +47,7 @@ export abstract class PolyModule<T extends ModuleType>
   protected superInitialized = false;
   private _voices!: number;
   private _name!: string;
+  private pendingUIUpdates = false;
 
   constructor(engineId: string, params: IPolyModuleConstructor<T>) {
     const { id, name, moduleType, voices, monoModuleConstructor, props } =
@@ -60,8 +61,7 @@ export abstract class PolyModule<T extends ModuleType>
     this.name = name;
     this.moduleType = moduleType;
     this.voices = voices || 1;
-    this._props = {} as ModuleTypeToPropsMapping[T];
-    this.props = props;
+    this._props = props;
 
     this.inputs = new InputCollection(
       this as unknown as PolyModule<ModuleType>,
@@ -71,6 +71,11 @@ export abstract class PolyModule<T extends ModuleType>
     );
 
     this.superInitialized = true;
+
+    // Defer hook calls until after subclass is fully initialized
+    queueMicrotask(() => {
+      this.props = props;
+    });
   }
 
   get name() {
@@ -166,6 +171,26 @@ export abstract class PolyModule<T extends ModuleType>
     audioModule.onMidiEvent(midiEvent);
   };
 
+  triggerPropsUpdate = () => {
+    if (this.pendingUIUpdates) return;
+
+    this.pendingUIUpdates = true;
+    this.sheduleTriggerUpdate();
+  };
+
+  private sheduleTriggerUpdate() {
+    requestAnimationFrame(() => {
+      this.engine._triggerPropsUpdate({
+        id: this.id,
+        moduleType: this.moduleType,
+        voices: this.voices,
+        name: this.name,
+        props: this.props,
+      });
+      this.pendingUIUpdates = false;
+    });
+  }
+
   findVoice(voiceNo: number) {
     const moduleByVoice = this.audioModules.find((m) => m.voiceNo === voiceNo);
     if (!moduleByVoice)

package/src/core/module/VoiceScheduler.ts

@@ -3,12 +3,13 @@ import { EmptyObject } from "@blibliki/utils";
 import { ICreateModule, ModuleType } from "@/modules";
 import { MidiOutput } from "../IO";
 import MidiEvent, { MidiEventType } from "../midi/MidiEvent";
-import { PropSchema } from "../schema";
+import { ModulePropSchema } from "../schema";
 import { IModuleConstructor, Module } from "./Module";
 import { IPolyModuleConstructor, PolyModule } from "./PolyModule";
 
 export type IVoiceSchedulerProps = EmptyObject;
-export const voiceSchedulerPropSchema: PropSchema<IVoiceSchedulerProps> = {};
+export const voiceSchedulerPropSchema: ModulePropSchema<IVoiceSchedulerProps> =
+  {};
 const DEFAULT_PROPS = {};
 
 class Voice extends Module<ModuleType.VoiceScheduler> {

package/src/core/module/index.ts

@@ -1,3 +1,3 @@
 export { Module } from "./Module";
-export type { IModule, IModuleSerialize } from "./Module";
+export type { IModule, IModuleSerialize, SetterHooks } from "./Module";
 export type { IPolyModule, IPolyModuleSerialize } from "./PolyModule";

package/src/core/schema.ts

@@ -1,3 +1,5 @@
+import { EmptyObject } from "@blibliki/utils";
+
 type BasePropType = {
   label?: string;
   description?: string;
@@ -8,6 +10,7 @@ export type NumberProp = BasePropType & {
   min?: number;
   max?: number;
   step?: number;
+  exp?: number;
 };
 
 export type EnumProp<T extends string | number> = BasePropType & {
@@ -28,14 +31,56 @@ export type ArrayProp = BasePropType & {
   kind: "array";
 };
 
-export type PropDefinition<T> = T extends number
-  ? NumberProp | EnumProp<number>
-  : T extends boolean
-    ? BooleanProp
-    : T extends string
-      ? StringProp | EnumProp<string>
-      : T extends (string | number)[]
+// Union of all possible prop schema types
+export type PropSchema =
+  | NumberProp
+  | EnumProp<string>
+  | EnumProp<number>
+  | StringProp
+  | BooleanProp
+  | ArrayProp;
+
+// Utility type to map TypeScript types to their primary schema types
+type PrimarySchemaForType<T> = T extends boolean
+  ? BooleanProp
+  : T extends string
+    ? StringProp
+    : T extends number
+      ? NumberProp
+      : T extends unknown[]
         ? ArrayProp
         : never;
 
-export type PropSchema<T> = { [K in keyof T]: PropDefinition<T[K]> };
+/**
+ * Schema type that maps each property to its primary schema type, with optional overrides.
+ * This provides excellent IntelliSense for both simple and complex cases.
+ *
+ * Basic usage:
+ * ```typescript
+ * type MyProps = { count: number; name: string; enabled: boolean };
+ * const mySchema: ModulePropSchema<MyProps> = {
+ *   count: { kind: "number", min: 0, max: 100 },
+ *   name: { kind: "string" },
+ *   enabled: { kind: "boolean" }
+ * };
+ * ```
+ *
+ * With overrides for custom schema types:
+ * ```typescript
+ * type MyProps = { wave: OscillatorWave; frequency: number };
+ * const mySchema: ModulePropSchema<MyProps, {
+ *   wave: EnumProp<OscillatorWave>
+ * }> = {
+ *   wave: { kind: "enum", options: Object.values(OscillatorWave) },
+ *   frequency: { kind: "number", min: 0, max: 1000 }
+ * };
+ * ```
+ */
+export type ModulePropSchema<
+  T,
+  TOverrides extends Partial<Record<keyof T, PropSchema>> = EmptyObject,
+> = {
+  [K in keyof T]: K extends keyof TOverrides
+    ? TOverrides[K]
+    : PrimarySchemaForType<T[K]>;
+};

package/src/index.ts

@@ -8,7 +8,7 @@ export type {
   IModuleSerialize,
   IPolyModuleSerialize,
   IMidiDevice,
-  PropDefinition,
+  ModulePropSchema,
   PropSchema,
   StringProp,
   NumberProp,
@@ -24,7 +24,12 @@ export type { TimeSignature, Position } from "@blibliki/transport";
 
 export { Context } from "@blibliki/utils";
 
-export { ModuleType, moduleSchemas, OscillatorWave } from "./modules";
+export {
+  ModuleType,
+  moduleSchemas,
+  OscillatorWave,
+  MidiMappingMode,
+} from "./modules";
 export type {
   IOscillator,
   IGain,
@@ -35,4 +40,7 @@ export type {
   ModuleTypeToPropsMapping,
   ICreateModule,
   ModuleParams,
+  IMidiMapper,
+  IMidiMapperProps,
+  MidiMapping,
 } from "./modules";

package/src/modules/Constant.ts

@@ -1,8 +1,7 @@
 import { ContextTime } from "@blibliki/transport";
 import { Context } from "@blibliki/utils";
-import { IModule, Module } from "@/core";
+import { IModule, Module, ModulePropSchema, SetterHooks } from "@/core";
 import Note from "@/core/Note";
-import { PropSchema } from "@/core/schema";
 import { ICreateModule, ModuleType } from ".";
 
 export type IConstant = IModule<ModuleType.Constant>;
@@ -10,7 +9,7 @@ export type IConstantProps = {
   value: number;
 };
 
-export const constantPropSchema: PropSchema<IConstantProps> = {
+export const constantPropSchema: ModulePropSchema<IConstantProps> = {
   value: {
     kind: "number",
     min: -Infinity,
@@ -22,7 +21,10 @@ export const constantPropSchema: PropSchema<IConstantProps> = {
 
 const DEFAULT_PROPS: IConstantProps = { value: 1 };
 
-export default class Constant extends Module<ModuleType.Constant> {
+export default class Constant
+  extends Module<ModuleType.Constant>
+  implements Pick<SetterHooks<IConstantProps>, "onAfterSetValue">
+{
   declare audioNode: ConstantSourceNode;
   isStated = false;
 
@@ -40,9 +42,9 @@ export default class Constant extends Module<ModuleType.Constant> {
     this.registerDefaultIOs("out");
   }
 
-  protected onSetValue(value: IConstantProps["value"]) {
+  onAfterSetValue: SetterHooks<IConstantProps>["onAfterSetValue"] = (value) => {
     this.audioNode.offset.value = value;
-  }
+  };
 
   start(time: ContextTime) {
     if (this.isStated) return;
@@ -52,6 +54,8 @@ export default class Constant extends Module<ModuleType.Constant> {
   }
 
   stop(time: ContextTime) {
+    if (!this.isStated) return;
+
     this.audioNode.stop(time);
     this.rePlugAll(() => {
       this.audioNode = new ConstantSourceNode(this.context.audioContext, {