yuzuthread 1.0.1 → 1.0.3

package/README.md

@@ -20,6 +20,22 @@ npm i yuzuthread typed-struct
 
 `typed-struct` is required because `yuzuthread` declares it as a peer dependency.
 
+### TypeScript Configuration
+
+Enable decorators in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+- `experimentalDecorators` is required for all decorators
+- `emitDecoratorMetadata` enables automatic type inference for `@TransportType()`
+
 ## Define a Worker Class
 
 Put each worker class in its own file and add `@DefineWorker()`.
@@ -138,22 +154,417 @@ console.log(instance.value); // -> 0x7f
 await instance.finalize();
 ```
 
+## Custom Class Transport
+
+By default, `worker_threads` can only pass serializable data (primitives, plain objects, `Buffer`, etc.). For custom classes, `yuzuthread` provides transport decorators to automatically serialize and deserialize instances.
+
+### Basic Class Transport
+
+Use `@TransportType()` to mark parameters and return values that need class restoration:
+
+```ts
+import { DefineWorker, WorkerMethod, TransportType, initWorker } from 'yuzuthread';
+
+class UserData {
+  constructor(
+    public id: number,
+    public name: string,
+  ) {}
+
+  greet() {
+    return `Hello, ${this.name}!`;
+  }
+}
+
+@DefineWorker()
+class DataWorker {
+  @WorkerMethod()
+  @TransportType(() => UserData)  // Return type
+  async processUser(
+    @TransportType(() => UserData) user: UserData,  // Parameter
+  ): Promise<UserData> {
+    return new UserData(user.id, user.name.toUpperCase());
+  }
+}
+
+const worker = await initWorker(DataWorker);
+const input = new UserData(1, 'alice');
+const result = await worker.processUser(input);
+
+console.log(result.greet()); // -> "Hello, ALICE!"
+await worker.finalize();
+```
+
+### Array Transport
+
+Use `[Class]` syntax for arrays:
+
+```ts
+@DefineWorker()
+class BatchWorker {
+  @WorkerMethod()
+  @TransportType(() => [UserData])
+  async processBatch(
+    @TransportType(() => [UserData]) users: UserData[],
+  ): Promise<UserData[]> {
+    return users.map((u) => new UserData(u.id + 100, u.name.toLowerCase()));
+  }
+}
+```
+
+### Nested Objects
+
+For classes with custom-class properties, add `@TransportType()` to the property:
+
+```ts
+class Address {
+  constructor(
+    public city: string,
+    public country: string,
+  ) {}
+}
+
+class Person {
+  @TransportType(() => Address)
+  address!: Address;
+
+  constructor(
+    public name: string,
+    address: Address,
+  ) {
+    this.address = address;
+  }
+}
+
+@DefineWorker()
+class PersonWorker {
+  @WorkerMethod()
+  @TransportType(() => Person)
+  async processPerson(
+    @TransportType(() => Person) person: Person,
+  ): Promise<Person> {
+    return new Person(
+      person.name,
+      new Address(person.address.city.toUpperCase(), person.address.country),
+    );
+  }
+}
+```
+
+### Custom Encoder
+
+For complex serialization logic, use `@TransportEncoder()`:
+
+```ts
+import { DefineWorker, WorkerMethod, TransportEncoder, initWorker } from 'yuzuthread';
+
+@DefineWorker()
+class DateWorker {
+  @WorkerMethod()
+  @TransportEncoder(
+    (date: Date) => date.toISOString(),
+    (str: string) => new Date(str),
+  )
+  async addDay(
+    @TransportEncoder(
+      (date: Date) => date.toISOString(),
+      (str: string) => new Date(str),
+    )
+    date: Date,
+  ): Promise<Date> {
+    const next = new Date(date);
+    next.setDate(next.getDate() + 1);
+    return next;
+  }
+}
+
+const worker = await initWorker(DateWorker);
+const today = new Date('2024-01-01');
+const tomorrow = await worker.addDay(today);
+console.log(tomorrow); // -> Date('2024-01-02')
+await worker.finalize();
+```
+
+Encoders support async operations:
+
+```ts
+@TransportEncoder(
+  async (obj: MyClass) => {
+    // async encoding logic
+    return await serialize(obj);
+  },
+  async (data: string) => {
+    // async decoding logic
+    return await deserialize(data);
+  },
+)
+```
+
+### Built-in Type Handling
+
+- **Primitives** (`string`, `number`, `boolean`, etc.) - passed as-is
+- **Built-in objects** (`Date`, `RegExp`, `Map`, `Set`, etc.) - handled by structured clone
+- **Buffer** - automatically encoded/decoded with `Uint8Array`
+- **TypedArrays** (`Uint8Array`, `Int32Array`, etc.) - passed directly
+- **Plain objects** - passed as-is
+- **Custom classes** - require `@TransportType()` or `@TransportEncoder()`
+
+### Typed Struct Classes
+
+Classes that extend `typed-struct` are automatically detected and handled with special transport logic. The library separates struct fields (stored in the buffer) from regular fields:
+
+```ts
+import { Struct } from 'typed-struct';
+import { DefineWorker, WorkerMethod, TransportType, initWorker } from 'yuzuthread';
+
+const Base = new Struct('DataBase')
+  .UInt8('id')
+  .UInt32LE('counter')
+  .compile();
+
+class MyData extends Base {
+  declare id: number;
+  declare counter: number;
+  extraField: string = '';
+  nestedData?: { name: string };
+}
+
+@DefineWorker()
+class StructWorker {
+  @WorkerMethod()
+  @TransportType(() => MyData)
+  async processData(
+    @TransportType(() => MyData) data?: MyData,
+  ): Promise<MyData> {
+    const result = new MyData();
+    if (data) {
+      result.id = data.id;
+      result.counter = data.counter + 1;
+      result.extraField = data.extraField + ' processed';
+      result.nestedData = data.nestedData;
+    } else {
+      result.id = 1;
+      result.counter = 0;
+      result.extraField = 'new';
+    }
+    return result;
+  }
+}
+
+const worker = await initWorker(StructWorker);
+const data = await worker.processData();
+console.log(data.id); // -> 1
+console.log(data.counter); // -> 0
+console.log(data.extraField); // -> 'new'
+```
+
+**How it works:**
+- When encoding, the library dumps the struct buffer and encodes non-struct fields separately
+- When decoding, it creates a new instance with the buffer, then restores non-struct fields
+- All struct fields (defined by `typed-struct`) are preserved in the buffer
+- Additional class fields are transported using the standard transport logic
+
+**Expected usage pattern:**
+```ts
+class SomeDataClass extends new Struct()...compile() {
+  // Struct fields (declare them for TypeScript)
+  declare structField1: number;
+  declare structField2: number;
+  
+  // Other fields (will be transported separately)
+  otherField: string = '';
+}
+```
+
+**Mixed scenarios with transport decorators:**
+
+Typed-struct classes can use `@TransportType()` and `@TransportEncoder()` on their non-struct fields:
+
+```ts
+class ComplexData extends Base {
+  declare value: number;  // struct field
+  declare count: number;  // struct field
+  
+  @TransportType(() => MyData)
+  nested?: MyData;  // non-struct field with custom class
+  
+  @TransportEncoder(
+    (date: Date) => date.toISOString(),
+    (str: string) => new Date(str),
+  )
+  timestamp?: Date;  // non-struct field with custom encoder
+}
+```
+
+Regular classes can have typed-struct fields:
+
+```ts
+class WrapperClass {
+  @TransportType(() => MyStructData)
+  data!: MyStructData;  // typed-struct class field
+  
+  label: string = '';  // regular field
+}
+```
+
+All combinations work seamlessly - the transport system automatically handles:
+- Typed-struct classes with decorated non-struct fields
+- Regular classes with typed-struct fields
+- Arrays of any of the above
+- Nested structures of any depth
+
+### Notes on Transport
+
+- `@TransportType()` can be used without arguments to enable `emitDecoratorMetadata` without registering metadata
+- Transport decorators work with both `@WorkerMethod()` and `@WorkerCallback()`
+- Multiple `@TransportType()` can be stacked (e.g., for method + parameters)
+- Encoding/decoding happens automatically during method calls
+- Transport uses structured clone algorithm with custom class restoration
+
+## Worker Status
+
+You can check the worker status at any time using `workerStatus()`:
+
+```ts
+const worker = await initWorker(CounterWorker);
+console.log(worker.workerStatus()); // -> 'Ready'
+
+await worker.increment(5);
+console.log(worker.workerStatus()); // -> 'Ready'
+
+await worker.finalize();
+console.log(worker.workerStatus()); // -> 'Finalized'
+```
+
+Possible status values (`WorkerStatus` enum):
+- `Initializing` - Worker is being created
+- `Ready` - Worker is ready to accept calls
+- `InitError` - Worker failed to initialize
+- `WorkerError` - Worker encountered a runtime error
+- `Exited` - Worker exited unexpectedly
+- `Finalized` - Worker was finalized via `finalize()`
+
+## Worker Event Handlers
+
+You can handle worker lifecycle events in the main thread using event decorators:
+
+```ts
+import { DefineWorker, WorkerMethod, OnWorkerEvent, OnWorkerExit, OnWorkerError, initWorker } from 'yuzuthread';
+
+@DefineWorker()
+class MonitoredWorker {
+  @WorkerMethod()
+  async doWork() {
+    // some work
+  }
+
+  @OnWorkerError()
+  handleError(error: Error) {
+    console.log('Worker error:', error.message);
+  }
+
+  @OnWorkerExit()
+  handleExit(code: number) {
+    console.log('Worker exited with code:', code);
+  }
+
+  @OnWorkerEvent('online')
+  handleOnline() {
+    console.log('Worker is online');
+  }
+
+  // One method can handle multiple events
+  @OnWorkerEvent('online')
+  @OnWorkerEvent('exit')
+  handleMultipleEvents(arg?: unknown) {
+    console.log('Worker online or exited');
+  }
+}
+
+const worker = await initWorker(MonitoredWorker);
+// Event handlers will be called automatically when events occur
+```
+
+Available decorators:
+- `@OnWorkerEvent(event: WorkerEventName)` - Handle any worker event (e.g., 'online', 'message', 'messageerror')
+  - `WorkerEventName` is typed to match `Worker.on()` events for type safety
+  - Can be stacked on the same method to handle multiple events
+- `@OnWorkerError()` - Shorthand for `@OnWorkerEvent('error')`
+- `@OnWorkerExit()` - Shorthand for `@OnWorkerEvent('exit')`
+
+Event handlers run on the main thread and can access the main-thread instance state. Multiple handlers can be registered for the same event, and one method can handle multiple events. If a handler throws an error, it will be logged but won't affect other handlers or worker operation.
+
 ## API
 
+### Decorators
+
+#### Worker Definition
+
 - `DefineWorker(options?)`
   - `options.filePath?`: worker file path override (optional, auto-inferred by default)
   - `options.id?`: custom class registration ID (optional)
+
+#### Method Execution
+
 - `WorkerMethod()`
   - marks a method to execute on worker thread
 - `WorkerCallback()`
   - marks a method to execute on main thread when called from worker
+
+#### Event Handlers
+
+- `OnWorkerEvent(event: WorkerEventName)`
+  - marks a method to handle worker events on main thread
+  - `WorkerEventName` is typed to match `Worker.on()` for type safety
+  - supports: 'error', 'exit', 'online', 'message', 'messageerror'
+  - can be stacked on the same method to handle multiple events
+- `OnWorkerError()`
+  - shorthand for `@OnWorkerEvent('error')`
+- `OnWorkerExit()`
+  - shorthand for `@OnWorkerEvent('exit')`
+
+#### Data Transport
+
+- `TransportType(factory?: () => Class | [Class])`
+  - marks parameter, return value, or property for custom class transport
+  - use `() => Class` for single instance
+  - use `() => [Class]` for arrays
+  - can be used without arguments to enable `emitDecoratorMetadata` only
+  - works as `PropertyDecorator`, `MethodDecorator`, and `ParameterDecorator`
+- `TransportEncoder<T, U>(encode, decode)`
+  - custom encoder/decoder for transport
+  - `encode: (obj: T) => Awaitable<U>` - serialize function
+  - `decode: (encoded: U) => Awaitable<T>` - deserialize function
+  - supports async operations
+  - works as `PropertyDecorator`, `MethodDecorator`, and `ParameterDecorator`
+
+### Functions
+
 - `initWorker(cls, ...args)`
-  - creates a persistent worker and returns instance with `finalize(): Promise<void>`
+  - creates a persistent worker and returns instance with `finalize(): Promise<void>` and `workerStatus(): WorkerStatus`
 - `runInWorker(cls, cb, ...args)`
   - one-time worker execution with automatic finalize
 
+### Types
+
+- `WorkerStatus`
+  - enum for worker status states
+- `WorkerInstance<T>`
+  - type for worker instance with `finalize()` and `workerStatus()` methods
+- `WorkerEventName`
+  - type for worker event names, matches `Worker.on()` event parameter
+- `Awaitable<T>`
+  - type for value that can be sync or async: `T | Promise<T>`
+- `TransportTypeFactory`
+  - type for transport type factory: `() => Class | [Class]`
+- `TransportEncoderType<T, U>`
+  - type for custom encoder/decoder object
+
 ## Notes
 
 - Worker classes are still normal classes when instantiated directly via `new`.
 - Only decorated methods go through the RPC channel.
 - TypeScript decorators require `experimentalDecorators`.
+- For `@TransportType()` to automatically infer types from TypeScript metadata, enable `emitDecoratorMetadata` in `tsconfig.json`.
+- Transport decorators work with both `@WorkerMethod()` and `@WorkerCallback()`.
+- Custom class transport preserves the prototype chain and method definitions.