yuzuthread 1.0.1

package/.eslintignore

@@ -0,0 +1,4 @@
+webpack.config.js
+dist/*
+build/*
+*.js

package/.eslintrc.js

@@ -0,0 +1,25 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: 'tsconfig.json',
+    tsconfigRootDir : __dirname, 
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint/eslint-plugin'],
+  extends: [
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended',
+  ],
+  root: true,
+  env: {
+    node: true,
+    jest: true,
+  },
+  ignorePatterns: ['.eslintrc.js'],
+  rules: {
+    '@typescript-eslint/interface-name-prefix': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+  },
+};

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/AGENTS.md

@@ -0,0 +1,23 @@
+# 项目要求
+
+## 项目规范
+
+- 能用 lambda 函数就用 lambda 函数，而不是 function。
+- 如果表达「类」类型，不要用 function，而是用 AnyClass 或者 ClassType<T>。
+- 如果写的代码属于和本业务无关的工具函数，那么写在 src/utility 下新开一个文件。并且要专门为这个文件写单元测试。
+- 和业务无关的类型放在 src/utility/types.ts 里。如果类型太长，那么另开文件。
+- 对于写的任何一个小方法，都要写单元测试 .spec.ts 然后跑一下验证对不对。
+- 测试的时候禁止同时跑两个命令，否则可能会有冲突。
+
+## 项目目标
+
+实现一个和 nanolith 差不多的库，可以用类创建 worker。
+
+## 参考代码
+
+下面的代码库可以作为参考，但是不要改里面的文件。
+注意不要尝试去 nanolith 找 typed-struct 相关的，不可能有的。
+
+- typed-struct: /Users/nanahira/nas-toa/workspace/ref/typed-struct
+- nanolith: /Users/nanahira/nas-toa/workspace/ref/typed-struct
+- typed-reflector: /Users/nanahira/nas-toa/workspace/typed-reflector

package/Dockerfile.puppeteer

@@ -0,0 +1,42 @@
+FROM node:lts-trixie-slim as base
+LABEL Author="Nanahira <nanahira@momobako.com>"
+
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends curl ca-certificates gnupg; \
+    install -d -m 0755 /etc/apt/keyrings; \
+    curl -fsSL https://dl.google.com/linux/linux_signing_key.pub \
+      | gpg --dearmor -o /etc/apt/keyrings/google-linux.gpg; \
+    chmod a+r /etc/apt/keyrings/google-linux.gpg; \
+    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google-linux.gpg] https://dl.google.com/linux/chrome/deb stable main" \
+      > /etc/apt/sources.list.d/google-chrome.list; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+      python3 build-essential git \
+      google-chrome-stable \
+      libnss3 libfreetype6-dev libharfbuzz-bin libharfbuzz-dev \
+      fonts-freefont-otf fonts-freefont-ttf \
+      fonts-noto-cjk fonts-noto-cjk-extra \
+      fonts-wqy-microhei fonts-wqy-zenhei \
+      xvfb; \
+    apt-get purge -y --auto-remove gnupg; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /var/log/*
+
+WORKDIR /usr/src/app
+COPY ./package*.json ./
+
+FROM base as builder
+RUN npm ci && npm cache clean --force
+COPY . ./
+RUN npm run build
+
+FROM base
+ENV NODE_ENV production
+RUN npm ci && npm cache clean --force
+COPY --from=builder /usr/src/app/dist ./dist
+
+CMD [ "npm", "start" ]

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Nanahira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,159 @@
+# yuzuthread
+
+A lightweight, class-first `worker_threads` library for Node.js.  
+Define a class with decorators, run methods in a worker thread, and keep a mirrored instance on the main thread.
+
+## Why
+
+`yuzuthread` is built around a few practical goals:
+
+- Organize worker logic with classes instead of manual message protocols.
+- Keep method calls ergonomic and object-oriented.
+- Automatically use shared memory for `typed-struct` classes.
+- Stay non-intrusive: your class can still be used with plain `new`.
+
+## Install
+
+```bash
+npm i yuzuthread typed-struct
+```
+
+`typed-struct` is required because `yuzuthread` declares it as a peer dependency.
+
+## Define a Worker Class
+
+Put each worker class in its own file and add `@DefineWorker()`.
+
+```ts
+// counter.worker.ts
+import { isMainThread } from 'node:worker_threads';
+import { DefineWorker, WorkerMethod, WorkerCallback } from 'yuzuthread';
+
+@DefineWorker()
+export class CounterWorker {
+  count = 0;
+
+  @WorkerMethod()
+  async increment(step: number) {
+    this.count += step;
+    return { count: this.count, isMainThread };
+  }
+
+  @WorkerMethod()
+  add(a: number, b: number) {
+    return a + b;
+  }
+
+  @WorkerCallback()
+  onMainAdd(a: number, b: number) {
+    this.count += a + b;
+    return { count: this.count, isMainThread };
+  }
+
+  @WorkerMethod()
+  async callMainAdd(a: number, b: number) {
+    return this.onMainAdd(a, b);
+  }
+}
+```
+
+## Long-running Worker (`initWorker`)
+
+`initWorker` creates a persistent worker instance.  
+Methods marked with `@WorkerMethod()` are proxied to the worker thread.  
+You still hold a main-thread instance of the same class.
+
+```ts
+import { initWorker } from 'yuzuthread';
+import { CounterWorker } from './counter.worker.js';
+
+const counter = await initWorker(CounterWorker);
+
+console.log(await counter.increment(2));
+// -> { count: 2, isMainThread: false }
+
+console.log(counter.count);
+// -> 0 (main-thread instance state)
+
+await counter.finalize();
+```
+
+## One-time Worker (`runInWorker`)
+
+`runInWorker` is for fire-and-forget style work: create worker, run callback, finalize automatically.
+
+```ts
+import { runInWorker } from 'yuzuthread';
+import { CounterWorker } from './counter.worker.js';
+
+const value = await runInWorker(
+  CounterWorker,
+  async (counter) => {
+    await counter.increment(2);
+    const result = await counter.increment(3);
+    return result.count;
+  },
+);
+
+console.log(value); // -> 5
+```
+
+## Reverse Calls with `WorkerCallback`
+
+`@WorkerCallback()` is the reverse direction:
+
+- Called on the main thread: runs locally like a normal method.
+- Called inside the worker thread: forwarded to main thread, then result is sent back.
+
+Use this when worker-side logic needs to call back into main-thread state or services.
+
+## `typed-struct` Shared Memory
+
+If a worker class inherits from a compiled `typed-struct` class, `yuzuthread` automatically:
+
+- Detects the struct class and computes buffer size.
+- Creates a `SharedArrayBuffer`.
+- Injects the shared buffer into both main-thread and worker-thread instances.
+
+So both sides operate on the same underlying memory.
+
+```ts
+import { Struct } from 'typed-struct';
+import { DefineWorker, WorkerMethod, initWorker } from 'yuzuthread';
+
+const Base = new Struct('SharedStructBase').UInt8('value').compile();
+
+@DefineWorker()
+class SharedStructWorker extends Base {
+  @WorkerMethod()
+  setValue(value: number) {
+    this.value = value;
+    return this.value;
+  }
+}
+
+const instance = await initWorker(SharedStructWorker, [0x10]);
+await instance.setValue(0x7f);
+console.log(instance.value); // -> 0x7f
+await instance.finalize();
+```
+
+## API
+
+- `DefineWorker(options?)`
+  - `options.filePath?`: worker file path override (optional, auto-inferred by default)
+  - `options.id?`: custom class registration ID (optional)
+- `WorkerMethod()`
+  - marks a method to execute on worker thread
+- `WorkerCallback()`
+  - marks a method to execute on main thread when called from worker
+- `initWorker(cls, ...args)`
+  - creates a persistent worker and returns instance with `finalize(): Promise<void>`
+- `runInWorker(cls, cb, ...args)`
+  - one-time worker execution with automatic finalize
+
+## Notes
+
+- Worker classes are still normal classes when instantiated directly via `new`.
+- Only decorated methods go through the RPC channel.
+- TypeScript decorators require `experimentalDecorators`.

package/dist/src/.nfs.200510fa.6938

@@ -0,0 +1,4 @@
+import { AnyClass } from 'nfkit';
+export declare const initWorker: <C extends AnyClass>(cls: C, ...args: ConstructorParameters<C>) => Promise<InstanceType<C> & {
+    finalize: () => Promise<void>;
+}>;

package/index.ts

@@ -0,0 +1,4 @@
+export * from './src/worker-method';
+export * from './src/worker';
+export * from './src/init-worker';
+export * from './src/run-in-worker';

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "yuzuthread",
+  "description": "Decorator-driven class workers for Node.js worker_threads with typed-struct shared memory.",
+  "version": "1.0.1",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "lint": "eslint --fix .",
+    "build": "node build.js",
+    "build:test": "npm run build && tsc -p tsconfig.test.json",
+    "build:cjs": "node build.js cjs",
+    "build:esm": "node build.js esm",
+    "build:types": "node build.js types",
+    "clean": "node build.js clean",
+    "test": "npm run build:test && jest --passWithNoTests",
+    "test:init-worker": "npm run build:test && jest --runInBand tests/init-worker.spec.ts",
+    "start": "node dist/index.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/purerosefallen/yuzuthread.git"
+  },
+  "author": "Nanahira <nanahira@momobako.com>",
+  "license": "MIT",
+  "keywords": [
+    "worker_threads",
+    "worker",
+    "decorator",
+    "typescript",
+    "rpc",
+    "typed-struct"
+  ],
+  "bugs": {
+    "url": "https://github.com/purerosefallen/yuzuthread/issues"
+  },
+  "homepage": "https://github.com/purerosefallen/yuzuthread#readme",
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "tests",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.2.2",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "esbuild": "^0.27.3",
+    "esbuild-register": "^3.6.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^29.7.0",
+    "prettier": "^3.8.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "typed-struct": "^2.7.1"
+  },
+  "dependencies": {
+    "nfkit": "^1.0.21",
+    "typed-reflector": "^1.0.14"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"compilerOptions": {
+		"outDir": "dist",
+		"module": "commonjs",
+		"target": "es2021",
+		"esModuleInterop": true,
+		"emitDecoratorMetadata": true,
+		"experimentalDecorators": true,
+		"declaration": true,
+		"sourceMap": true
+	},
+	"compileOnSave": true,
+	"allowJs": true,
+	"include": [
+		"*.ts",
+		"src/**/*.ts",
+		"test/**/*.ts",
+		"tests/**/*.ts"
+	]
+}

package/tsconfig.test.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "commonjs",
+    "outDir": ".",
+    "rootDir": ".",
+    "declaration": false,
+    "sourceMap": false,
+    "removeComments": false,
+    "noEmit": false
+  },
+  "include": [
+    "tests/fixtures/**/*.ts"
+  ],
+  "exclude": []
+}