@simplysm/core-node 14.0.1 → 14.0.4

package/README.md

@@ -0,0 +1,126 @@
+# @simplysm/core-node
+
+Core Node.js utilities -- file system operations, path utilities, file watcher, typed worker threads.
+
+## Installation
+
+```bash
+npm install @simplysm/core-node
+```
+
+## API
+
+### fsx -- File System Utilities
+
+Namespace with sync/async file system operations. See [docs/fsx.md](docs/fsx.md) for full API.
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `existsSync` | `(targetPath: string): boolean` | Check if path exists (sync) |
+| `exists` | `(targetPath: string): Promise<boolean>` | Check if path exists (async) |
+| `mkdirSync` | `(targetPath: string): void` | Create directory recursively (sync) |
+| `mkdir` | `(targetPath: string): Promise<void>` | Create directory recursively (async) |
+| `rmSync` | `(targetPath: string): void` | Remove file/directory (sync) |
+| `rm` | `(targetPath: string): Promise<void>` | Remove file/directory with retry (async) |
+| `copySync` | `(sourcePath, targetPath, filter?): void` | Copy file/directory (sync) |
+| `copy` | `(sourcePath, targetPath, filter?): Promise<void>` | Copy file/directory (async) |
+| `readSync` | `(targetPath: string): string` | Read file as UTF-8 string (sync) |
+| `read` | `(targetPath: string): Promise<string>` | Read file as UTF-8 string (async) |
+| `readBufferSync` | `(targetPath: string): Buffer` | Read file as Buffer (sync) |
+| `readBuffer` | `(targetPath: string): Promise<Buffer>` | Read file as Buffer (async) |
+| `readJsonSync` | `<T>(targetPath: string): T` | Read and parse JSON file (sync) |
+| `readJson` | `<T>(targetPath: string): Promise<T>` | Read and parse JSON file (async) |
+| `writeSync` | `(targetPath, data): void` | Write file with auto-mkdir (sync) |
+| `write` | `(targetPath, data): Promise<void>` | Write file with auto-mkdir (async) |
+| `writeJsonSync` | `(targetPath, data, options?): void` | Write JSON file (sync) |
+| `writeJson` | `(targetPath, data, options?): Promise<void>` | Write JSON file (async) |
+| `readdirSync` | `(targetPath: string): string[]` | List directory contents (sync) |
+| `readdir` | `(targetPath: string): Promise<string[]>` | List directory contents (async) |
+| `statSync` | `(targetPath: string): fs.Stats` | Get file info, follows symlinks (sync) |
+| `stat` | `(targetPath: string): Promise<fs.Stats>` | Get file info, follows symlinks (async) |
+| `lstatSync` | `(targetPath: string): fs.Stats` | Get file info, no symlink follow (sync) |
+| `lstat` | `(targetPath: string): Promise<fs.Stats>` | Get file info, no symlink follow (async) |
+| `globSync` | `(pattern, options?): string[]` | Glob file search (sync) |
+| `glob` | `(pattern, options?): Promise<string[]>` | Glob file search (async) |
+| `clearEmptyDirectory` | `(dirPath: string): Promise<void>` | Recursively remove empty directories |
+| `findAllParentChildPathsSync` | `(childGlob, fromPath, rootPath?): string[]` | Search parent dirs for glob matches (sync) |
+| `findAllParentChildPaths` | `(childGlob, fromPath, rootPath?): Promise<string[]>` | Search parent dirs for glob matches (async) |
+
+### pathx -- Path Utilities
+
+Namespace with path manipulation utilities. See [docs/pathx.md](docs/pathx.md) for full API.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `NormPath` | type | Branded type for normalized absolute paths |
+| `posix` | function | Convert path to POSIX style (backslash to slash) |
+| `changeFileDirectory` | function | Change the directory portion of a file path |
+| `basenameWithoutExt` | function | Get filename without extension |
+| `isChildPath` | function | Check if a path is a child of another |
+| `norm` | function | Normalize and resolve path to `NormPath` |
+| `filterByTargets` | function | Filter file paths by target directory prefixes |
+
+### FsWatcher -- File System Watcher
+
+Chokidar-based file watcher with debounced change events. See [docs/fs-watcher.md](docs/fs-watcher.md) for full API.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `FsWatcherEvent` | type | `"add" \| "addDir" \| "change" \| "unlink" \| "unlinkDir"` |
+| `FsWatcherChangeInfo` | interface | Change event info with path and event type |
+| `FsWatcher` | class | Debounced file system watcher |
+
+### Worker -- Typed Worker Threads
+
+Type-safe worker thread wrapper with Proxy-based RPC. See [docs/worker.md](docs/worker.md) for full API.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `WorkerModule` | interface | Type structure for worker modules |
+| `PromisifyMethods` | type | Maps sync method signatures to async |
+| `WorkerProxy` | type | Proxy type returned by `Worker.create()` |
+| `WorkerRequest` | interface | Internal worker request message |
+| `WorkerResponse` | type | Internal worker response message (union) |
+| `Worker` | const | Factory object with `create()` method |
+| `createWorker` | function | Define a worker module in a worker thread |
+
+## Usage
+
+```ts
+import { fsx, pathx } from "@simplysm/core-node";
+
+// File system
+await fsx.mkdir("/tmp/mydir");
+await fsx.write("/tmp/mydir/hello.txt", "Hello, world!");
+const content = await fsx.read("/tmp/mydir/hello.txt");
+const config = await fsx.readJson<{ port: number }>("config.json");
+
+// Path utilities
+const posixPath = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
+const normalized = pathx.norm("/some/path");      // NormPath
+const isChild = pathx.isChildPath("/a/b/c", "/a/b"); // true
+
+// File watcher
+import { FsWatcher } from "@simplysm/core-node";
+
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { path, event } of changes) {
+    console.log(`${event}: ${path}`);
+  }
+});
+await watcher.close();
+
+// Worker threads
+import { Worker, createWorker } from "@simplysm/core-node";
+
+// worker.ts
+export default createWorker({
+  add: (a: number, b: number) => a + b,
+});
+
+// main.ts
+const worker = Worker.create<typeof import("./worker")>("./worker.ts");
+const result = await worker.add(10, 20); // 30
+await worker.terminate();
+```

package/docs/fs-watcher.md

@@ -0,0 +1,107 @@
+# FsWatcher -- File System Watcher
+
+Chokidar-based file system watcher with debounced event delivery and glob filtering.
+
+```ts
+import { FsWatcher } from "@simplysm/core-node";
+import type { FsWatcherEvent, FsWatcherChangeInfo } from "@simplysm/core-node";
+```
+
+## Types
+
+### FsWatcherEvent
+
+```ts
+type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir"
+```
+
+Supported file change event types.
+
+### FsWatcherChangeInfo (interface)
+
+```ts
+interface FsWatcherChangeInfo {
+  event: FsWatcherEvent;
+  path: NormPath;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `event` | `FsWatcherEvent` | The type of change event |
+| `path` | `NormPath` | Normalized absolute path of the changed file/directory |
+
+## FsWatcher (class)
+
+Wraps chokidar to provide debounced file change notifications. Multiple events occurring within a short window are merged and delivered as a single batch.
+
+Event merging strategy:
+- `add` + `change` --> `add` (modification right after creation is treated as creation)
+- `add` + `unlink` --> removed (creation then deletion cancels out)
+- `unlink` + `add` --> `add` (deletion then recreation is treated as creation)
+- Other combinations --> latest event wins
+
+**Note:** `ignoreInitial` is always set to `true` internally. Passing `ignoreInitial: false` triggers an initial callback with an empty array, but does not include the initial file listing.
+
+### Static Methods
+
+#### FsWatcher.watch
+
+```ts
+static async watch(
+  paths: string[],
+  options?: chokidar.ChokidarOptions,
+): Promise<FsWatcher>
+```
+
+Start watching files/directories. Resolves when the watcher is ready.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `paths` | `string[]` | File paths, directory paths, or glob patterns to watch |
+| `options` | `chokidar.ChokidarOptions?` | Chokidar configuration options |
+
+Glob patterns in `paths` are automatically decomposed: the base directory is watched, and events are filtered by the glob pattern using minimatch.
+
+### Instance Methods
+
+#### onChange
+
+```ts
+onChange(
+  opt: { delay?: number },
+  cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>,
+): this
+```
+
+Register a change event handler. Events are collected for the specified delay duration and delivered as a single batch.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opt.delay` | `number?` | Debounce delay in milliseconds |
+| `cb` | `(changeInfos: FsWatcherChangeInfo[]) => void \| Promise<void>` | Callback receiving batched change events |
+
+Returns `this` for chaining.
+
+#### close
+
+```ts
+async close(): Promise<void>
+```
+
+Stop watching and clean up all debounce queues.
+
+## Usage
+
+```ts
+const watcher = await FsWatcher.watch(["src/**/*.ts"], { depth: 3 });
+
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { path, event } of changes) {
+    console.log(`${event}: ${path}`);
+  }
+});
+
+// Later: stop watching
+await watcher.close();
+```

package/docs/fsx.md

@@ -0,0 +1,287 @@
+# fsx -- File System Utilities
+
+Namespace providing sync and async file system operations with automatic error wrapping, recursive directory creation, and glob support.
+
+```ts
+import { fsx } from "@simplysm/core-node";
+```
+
+## Functions
+
+### existsSync
+
+```ts
+function existsSync(targetPath: string): boolean
+```
+
+Check if a file or directory exists (synchronous).
+
+### exists
+
+```ts
+async function exists(targetPath: string): Promise<boolean>
+```
+
+Check if a file or directory exists (asynchronous).
+
+### mkdirSync
+
+```ts
+function mkdirSync(targetPath: string): void
+```
+
+Create a directory recursively (synchronous). Equivalent to `mkdir -p`.
+
+### mkdir
+
+```ts
+async function mkdir(targetPath: string): Promise<void>
+```
+
+Create a directory recursively (asynchronous). Equivalent to `mkdir -p`.
+
+### rmSync
+
+```ts
+function rmSync(targetPath: string): void
+```
+
+Remove a file or directory recursively (synchronous). Does not retry on failure -- use `rm` if transient errors (e.g., file locks) are expected.
+
+### rm
+
+```ts
+async function rm(targetPath: string): Promise<void>
+```
+
+Remove a file or directory recursively (asynchronous). Retries up to 6 times with 500ms delay on transient errors.
+
+### copySync
+
+```ts
+function copySync(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): void
+```
+
+Copy a file or directory recursively (synchronous).
+
+- If `sourcePath` does not exist, returns silently.
+- `filter` receives the absolute path of each child entry. Return `true` to include, `false` to exclude.
+- The top-level `sourcePath` is not subject to filtering -- only its descendants are.
+- Returning `false` for a directory skips it and all its contents.
+
+### copy
+
+```ts
+async function copy(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): Promise<void>
+```
+
+Copy a file or directory recursively (asynchronous). Same semantics as `copySync`.
+
+### readSync
+
+```ts
+function readSync(targetPath: string): string
+```
+
+Read a file as a UTF-8 string (synchronous).
+
+### read
+
+```ts
+async function read(targetPath: string): Promise<string>
+```
+
+Read a file as a UTF-8 string (asynchronous).
+
+### readBufferSync
+
+```ts
+function readBufferSync(targetPath: string): Buffer
+```
+
+Read a file as a `Buffer` (synchronous).
+
+### readBuffer
+
+```ts
+async function readBuffer(targetPath: string): Promise<Buffer>
+```
+
+Read a file as a `Buffer` (asynchronous).
+
+### readJsonSync
+
+```ts
+function readJsonSync<TData = unknown>(targetPath: string): TData
+```
+
+Read and parse a JSON file using `json.parse` from `@simplysm/core-common` (synchronous). On parse failure, the error message includes a preview of the file contents.
+
+### readJson
+
+```ts
+async function readJson<TData = unknown>(targetPath: string): Promise<TData>
+```
+
+Read and parse a JSON file using `json.parse` from `@simplysm/core-common` (asynchronous). On parse failure, the error message includes a preview of the file contents.
+
+### writeSync
+
+```ts
+function writeSync(targetPath: string, data: string | Uint8Array): void
+```
+
+Write data to a file (synchronous). Parent directories are created automatically. The file is flushed to disk.
+
+### write
+
+```ts
+async function write(targetPath: string, data: string | Uint8Array): Promise<void>
+```
+
+Write data to a file (asynchronous). Parent directories are created automatically. The file is flushed to disk.
+
+### writeJsonSync
+
+```ts
+function writeJsonSync(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): void
+```
+
+Serialize data to JSON and write to a file (synchronous). Uses `json.stringify` from `@simplysm/core-common`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `replacer` | `(this: unknown, key: string \| undefined, value: unknown) => unknown` | Custom replacer function |
+| `space` | `string \| number` | Indentation (spaces or string) |
+
+### writeJson
+
+```ts
+async function writeJson(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): Promise<void>
+```
+
+Serialize data to JSON and write to a file (asynchronous). Uses `json.stringify` from `@simplysm/core-common`. Same options as `writeJsonSync`.
+
+### readdirSync
+
+```ts
+function readdirSync(targetPath: string): string[]
+```
+
+Read directory contents (synchronous). Returns an array of entry names.
+
+### readdir
+
+```ts
+async function readdir(targetPath: string): Promise<string[]>
+```
+
+Read directory contents (asynchronous). Returns an array of entry names.
+
+### statSync
+
+```ts
+function statSync(targetPath: string): fs.Stats
+```
+
+Get file/directory info (synchronous). Follows symbolic links.
+
+### stat
+
+```ts
+async function stat(targetPath: string): Promise<fs.Stats>
+```
+
+Get file/directory info (asynchronous). Follows symbolic links.
+
+### lstatSync
+
+```ts
+function lstatSync(targetPath: string): fs.Stats
+```
+
+Get file/directory info (synchronous). Does **not** follow symbolic links.
+
+### lstat
+
+```ts
+async function lstat(targetPath: string): Promise<fs.Stats>
+```
+
+Get file/directory info (asynchronous). Does **not** follow symbolic links.
+
+### globSync
+
+```ts
+function globSync(pattern: string, options?: GlobOptions): string[]
+```
+
+Search for files matching a glob pattern (synchronous). Returns absolute paths. Backslashes in the pattern are converted to forward slashes.
+
+### glob
+
+```ts
+async function glob(pattern: string, options?: GlobOptions): Promise<string[]>
+```
+
+Search for files matching a glob pattern (asynchronous). Returns absolute paths. Backslashes in the pattern are converted to forward slashes.
+
+### clearEmptyDirectory
+
+```ts
+async function clearEmptyDirectory(dirPath: string): Promise<void>
+```
+
+Recursively find and remove empty directories under `dirPath`. If removing children causes a parent directory to become empty, it is also removed.
+
+### findAllParentChildPathsSync
+
+```ts
+function findAllParentChildPathsSync(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): string[]
+```
+
+Walk from `fromPath` toward the filesystem root, collecting all files matching `childGlob` in each directory (synchronous).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `childGlob` | `string` | Glob pattern to match in each directory |
+| `fromPath` | `string` | Starting path for the upward walk |
+| `rootPath` | `string?` | Stop path (defaults to filesystem root). `fromPath` must be a descendant of `rootPath`. |
+
+### findAllParentChildPaths
+
+```ts
+async function findAllParentChildPaths(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): Promise<string[]>
+```
+
+Walk from `fromPath` toward the filesystem root, collecting all files matching `childGlob` in each directory (asynchronous). Same parameters as `findAllParentChildPathsSync`.

package/docs/pathx.md

@@ -0,0 +1,115 @@
+# pathx -- Path Utilities
+
+Namespace providing path manipulation utilities with normalization, POSIX conversion, and filtering.
+
+```ts
+import { pathx } from "@simplysm/core-node";
+```
+
+## Types
+
+### NormPath
+
+```ts
+type NormPath = string & { [NORM]: never }
+```
+
+Branded type representing a normalized absolute path. Can only be created via `norm()`. The brand prevents accidental use of raw strings where a normalized path is expected.
+
+## Functions
+
+### posix
+
+```ts
+function posix(...args: string[]): string
+```
+
+Convert a path to POSIX style by joining the arguments and replacing backslashes with forward slashes.
+
+```ts
+pathx.posix("C:\\Users\\test");    // "C:/Users/test"
+pathx.posix("src", "index.ts");   // "src/index.ts"
+```
+
+### changeFileDirectory
+
+```ts
+function changeFileDirectory(
+  filePath: string,
+  fromDirectory: string,
+  toDirectory: string,
+): string
+```
+
+Change the directory portion of a file path. The file must be inside `fromDirectory`; throws `ArgumentError` otherwise.
+
+```ts
+pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x");
+// "/x/b/c.txt"
+```
+
+### basenameWithoutExt
+
+```ts
+function basenameWithoutExt(filePath: string): string
+```
+
+Return the filename without its extension.
+
+```ts
+pathx.basenameWithoutExt("file.txt");            // "file"
+pathx.basenameWithoutExt("/path/to/file.spec.ts"); // "file.spec"
+```
+
+### isChildPath
+
+```ts
+function isChildPath(childPath: string, parentPath: string): boolean
+```
+
+Check if `childPath` is a descendant of `parentPath`. Returns `false` for identical paths. Paths are normalized internally via `norm()`.
+
+```ts
+pathx.isChildPath("/a/b/c", "/a/b"); // true
+pathx.isChildPath("/a/b", "/a/b/c"); // false
+pathx.isChildPath("/a/b", "/a/b");   // false (same path)
+```
+
+### norm
+
+```ts
+function norm(...paths: string[]): NormPath
+```
+
+Normalize and resolve path segments into an absolute `NormPath`. Uses the platform-specific path separator.
+
+```ts
+pathx.norm("/some/path");          // NormPath
+pathx.norm("relative", "path");   // NormPath (resolved to absolute)
+```
+
+### filterByTargets
+
+```ts
+function filterByTargets(
+  files: string[],
+  targets: string[],
+  cwd: string,
+): string[]
+```
+
+Filter file paths by target directory prefixes.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `files` | `string[]` | Absolute file paths to filter (must be under `cwd`) |
+| `targets` | `string[]` | Target directory prefixes (relative to `cwd`, POSIX style recommended) |
+| `cwd` | `string` | Current working directory (absolute path) |
+
+Returns `files` unchanged if `targets` is empty. Otherwise returns only files whose relative path matches or is a child of a target.
+
+```ts
+const files = ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"];
+pathx.filterByTargets(files, ["src"], "/proj");
+// ["/proj/src/a.ts", "/proj/src/b.ts"]
+```

package/docs/worker.md

@@ -0,0 +1,223 @@
+# Worker -- Typed Worker Threads
+
+Type-safe worker thread wrapper providing Proxy-based RPC and event communication between the main thread and worker threads.
+
+```ts
+import { Worker, createWorker } from "@simplysm/core-node";
+import type {
+  WorkerModule,
+  PromisifyMethods,
+  WorkerProxy,
+  WorkerRequest,
+  WorkerResponse,
+} from "@simplysm/core-node";
+```
+
+## Types
+
+### WorkerModule (interface)
+
+```ts
+interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+```
+
+Type structure representing a worker module. Used with `Worker.create<typeof import("./worker")>()` for type inference.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `default.__methods` | `Record<string, (...args: any[]) => unknown>` | Map of callable worker methods |
+| `default.__events` | `Record<string, unknown>` | Map of event names to event data types |
+
+### PromisifyMethods
+
+```ts
+type PromisifyMethods<TMethods> = {
+  [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+}
+```
+
+Utility type that wraps all method return types in `Promise`. Worker methods communicate via `postMessage` and are inherently asynchronous, so even synchronous method signatures are converted to `Promise<Awaited<R>>`.
+
+### WorkerProxy
+
+```ts
+type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
+  TModule["default"]["__methods"]
+> & {
+  on<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+
+  off<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+
+  terminate(): Promise<void>;
+}
+```
+
+The proxy type returned by `Worker.create()`. Combines promisified worker methods with event handling and termination.
+
+| Method | Description |
+|--------|-------------|
+| `on(event, listener)` | Register an event listener |
+| `off(event, listener)` | Remove an event listener |
+| `terminate()` | Terminate the worker thread |
+
+### WorkerRequest (interface)
+
+```ts
+interface WorkerRequest {
+  id: string;
+  method: string;
+  params: unknown[];
+}
+```
+
+Internal message format sent from the main thread to the worker.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique request identifier (UUID) |
+| `method` | `string` | Name of the method to invoke |
+| `params` | `unknown[]` | Method arguments |
+
+### WorkerResponse (type)
+
+```ts
+type WorkerResponse =
+  | { request: WorkerRequest; type: "return"; body?: unknown }
+  | { request: WorkerRequest; type: "error"; body: Error }
+  | { type: "event"; event: string; body?: unknown }
+  | { type: "log"; body: string }
+```
+
+Internal message format sent from the worker to the main thread. A discriminated union with four variants:
+
+| Variant | Fields | Description |
+|---------|--------|-------------|
+| `return` | `request`, `body?` | Successful method return value |
+| `error` | `request`, `body` | Method threw an error |
+| `event` | `event`, `body?` | Worker-emitted event |
+| `log` | `body` | Redirected stdout output |
+
+## Worker (const)
+
+Factory object for creating type-safe worker proxies.
+
+### Worker.create
+
+```ts
+Worker.create<TModule extends WorkerModule>(
+  filePath: string,
+  opt?: Omit<WorkerRawOptions, "stdout" | "stderr">,
+): WorkerProxy<TModule>
+```
+
+Create a type-safe worker proxy.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | `string` | Worker file path (`file://` URL or absolute path) |
+| `opt` | `Omit<WorkerRawOptions, "stdout" \| "stderr">?` | Node.js `WorkerOptions` (excluding stdout/stderr which are managed internally) |
+
+In development (`.ts` files), the worker is loaded via `tsx`. In production (`.js` files), the worker is loaded directly.
+
+Worker stdout/stderr is piped to the main process. On abnormal exit, all pending requests are rejected.
+
+## createWorker (function)
+
+```ts
+function createWorker<
+  TMethods extends Record<string, (...args: any[]) => unknown>,
+  TEvents extends Record<string, unknown> = Record<string, never>,
+>(
+  methods: TMethods,
+): {
+  send<TEventName extends keyof TEvents & string>(
+    event: TEventName,
+    data?: TEvents[TEventName],
+  ): void;
+  __methods: TMethods;
+  __events: TEvents;
+}
+```
+
+Define a worker module inside a worker thread file. Returns a sender object that can emit events to the main thread.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `methods` | `TMethods` | Object mapping method names to handler functions |
+
+The returned object exposes:
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `send(event, data?)` | Emit a typed event to the main thread |
+| `__methods` | Type-level reference to the methods map (used for type inference) |
+| `__events` | Type-level reference to the events map (used for type inference) |
+
+Throws if not running in a worker thread (`parentPort` is null).
+
+## Usage
+
+### Basic worker (no events)
+
+```ts
+// math-worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+export default createWorker({
+  add: (a: number, b: number) => a + b,
+  multiply: (a: number, b: number) => a * b,
+});
+
+// main.ts
+import { Worker } from "@simplysm/core-node";
+
+const worker = Worker.create<typeof import("./math-worker")>("./math-worker.ts");
+const sum = await worker.add(10, 20);       // 30
+const product = await worker.multiply(3, 7); // 21
+await worker.terminate();
+```
+
+### Worker with events
+
+```ts
+// process-worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+interface Events {
+  progress: number;
+}
+
+const methods = {
+  processData: (items: string[]) => {
+    for (let i = 0; i < items.length; i++) {
+      // ... process item ...
+      sender.send("progress", ((i + 1) / items.length) * 100);
+    }
+    return items.length;
+  },
+};
+
+const sender = createWorker<typeof methods, Events>(methods);
+export default sender;
+
+// main.ts
+import { Worker } from "@simplysm/core-node";
+
+const worker = Worker.create<typeof import("./process-worker")>("./process-worker.ts");
+worker.on("progress", (pct) => console.log(`${pct}% done`));
+const count = await worker.processData(["a", "b", "c"]);
+await worker.terminate();
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-node",
-  "version": "14.0.1",
+  "version": "14.0.4",
   "description": "심플리즘 패키지 - 코어 (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "src",
-    "lib"
+    "lib",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -24,9 +25,9 @@
     "glob": "^13.0.6",
     "minimatch": "^10.2.4",
     "tsx": "^4.21.0",
-    "@simplysm/core-common": "14.0.1"
+    "@simplysm/core-common": "14.0.4"
   },
   "devDependencies": {
-    "@types/node": "^20.14.8"
+    "@types/node": "^20.19.37"
   }
 }