@simplysm/core-node 14.0.1 → 14.0.5

package/README.md

@@ -0,0 +1,155 @@
+# @simplysm/core-node
+
+Node.js-specific core utilities for the Simplysm framework. Provides enhanced file system operations, path utilities, file watching, and a type-safe worker thread abstraction.
+
+## Installation
+
+```bash
+npm install @simplysm/core-node
+```
+
+## API Overview
+
+### Utilities / fsx
+
+Namespace `fsx` -- Enhanced file system functions (sync and async pairs).
+
+| API | Type | Description |
+|-----|------|-------------|
+| `exists` | function | Check if a path exists (async) |
+| `existsSync` | function | Check if a path exists (sync) |
+| `mkdir` | function | Create directory recursively (async) |
+| `mkdirSync` | function | Create directory recursively (sync) |
+| `rm` | function | Remove file/directory with retry (async) |
+| `rmSync` | function | Remove file/directory (sync) |
+| `copy` | function | Copy file/directory with filter (async) |
+| `copySync` | function | Copy file/directory with filter (sync) |
+| `read` | function | Read file as UTF-8 string (async) |
+| `readSync` | function | Read file as UTF-8 string (sync) |
+| `readBuffer` | function | Read file as Buffer (async) |
+| `readBufferSync` | function | Read file as Buffer (sync) |
+| `readJson` | function | Read and parse JSON file (async) |
+| `readJsonSync` | function | Read and parse JSON file (sync) |
+| `write` | function | Write data to file (async) |
+| `writeSync` | function | Write data to file (sync) |
+| `writeJson` | function | Write data as JSON file (async) |
+| `writeJsonSync` | function | Write data as JSON file (sync) |
+| `readdir` | function | List directory contents (async) |
+| `readdirSync` | function | List directory contents (sync) |
+| `stat` | function | Get file stats, follows symlinks (async) |
+| `statSync` | function | Get file stats, follows symlinks (sync) |
+| `lstat` | function | Get file stats, no symlink follow (async) |
+| `lstatSync` | function | Get file stats, no symlink follow (sync) |
+| `glob` | function | Search files by glob pattern (async) |
+| `globSync` | function | Search files by glob pattern (sync) |
+| `clearEmptyDirectory` | function | Recursively remove empty directories (async) |
+| `findAllParentChildPaths` | function | Search parent dirs for glob matches (async) |
+| `findAllParentChildPathsSync` | function | Search parent dirs for glob matches (sync) |
+
+> See [docs/fsx.md](./docs/fsx.md) for details.
+
+### Utilities / pathx
+
+Namespace `pathx` -- Path manipulation utilities.
+
+| API | Type | Description |
+|-----|------|-------------|
+| `NormPath` | type | Branded string type for normalized paths |
+| `posix` | function | Convert path to POSIX style (backslash to slash) |
+| `changeFileDirectory` | function | Change a file's parent directory |
+| `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 |
+
+> See [docs/pathx.md](./docs/pathx.md) for details.
+
+### Features
+
+| API | Type | Description |
+|-----|------|-------------|
+| `FsWatcherEvent` | type | File change event type union |
+| `FsWatcherChangeInfo` | interface | File change event info |
+| `FsWatcher` | class | Debounced file system watcher (chokidar-based) |
+
+> See [docs/fs-watcher.md](./docs/fs-watcher.md) for details.
+
+### Worker
+
+| API | Type | Description |
+|-----|------|-------------|
+| `WorkerModule` | interface | Type structure for worker modules |
+| `PromisifyMethods` | type | Maps sync methods to async (Promise) |
+| `WorkerProxy` | type | Proxy type returned by `Worker.create()` |
+| `WorkerRequest` | interface | Internal worker request message |
+| `WorkerResponse` | type | Internal worker response message |
+| `Worker` | object | Type-safe worker thread factory |
+| `createWorker` | function | Create a worker module in the worker thread |
+
+> See [docs/worker.md](./docs/worker.md) for details.
+
+## Usage Examples
+
+### File system operations
+
+```typescript
+import { fsx } from "@simplysm/core-node";
+
+// Read/write files
+const content = await fsx.read("/path/to/file.txt");
+await fsx.write("/path/to/output.txt", "hello");
+
+// JSON
+const data = await fsx.readJson<{ name: string }>("/path/to/config.json");
+await fsx.writeJson("/path/to/out.json", data, { space: 2 });
+
+// Copy with filter
+await fsx.copy("/src", "/dest", (p) => !p.endsWith(".tmp"));
+
+// Glob
+const tsFiles = await fsx.glob("/project/src/**/*.ts");
+```
+
+### Path utilities
+
+```typescript
+import { pathx } from "@simplysm/core-node";
+
+const p = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
+const name = pathx.basenameWithoutExt("file.spec.ts"); // "file.spec"
+const isChild = pathx.isChildPath("/a/b/c", "/a/b"); // true
+const norm = pathx.norm("/some/path"); // NormPath
+```
+
+### File watcher
+
+```typescript
+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
+
+```typescript
+// worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+export default createWorker({
+  add: (a: number, b: number) => a + b,
+});
+
+// main.ts
+import { Worker } from "@simplysm/core-node";
+
+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,105 @@
+# FsWatcher
+
+Chokidar-based file system watcher with debounced event merging. Short-lived events on the same file are consolidated into a single callback invocation.
+
+```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
+
+```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
+
+Debounced file system watcher. Events occurring within the debounce window are merged using the following 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
+
+The constructor is private; use the static `watch` method.
+
+**Note:** `ignoreInitial` is always forced to `true` internally. If you pass `ignoreInitial: false`, the first `onChange` callback fires with an empty array (initial file listing is not included).
+
+### Static Methods
+
+#### FsWatcher.watch
+
+```ts
+static async watch(
+  paths: string[],
+  options?: chokidar.ChokidarOptions,
+): Promise<FsWatcher>
+```
+
+Start watching files/directories (async). Resolves when chokidar emits the `ready` event.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `paths` | `string[]` | File/directory paths or glob patterns to watch |
+| `options` | `chokidar.ChokidarOptions` | Chokidar options (except `ignoreInitial`, which is forced `true`) |
+
+### Instance Methods
+
+#### onChange
+
+```ts
+onChange(
+  opt: { delay?: number },
+  cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>,
+): this
+```
+
+Register a file change event handler. Events are collected for the specified delay, then delivered as a 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 the watcher and dispose 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,314 @@
+# fsx
+
+Namespace of enhanced file system functions. All functions wrap Node.js `fs` with error handling (wrapping in `SdError`) and convenience features like recursive directory creation. Most functions come in sync/async pairs.
+
+Imported as:
+```typescript
+import { fsx } from "@simplysm/core-node";
+```
+
+## Existence
+
+### existsSync
+
+```ts
+function existsSync(targetPath: string): boolean
+```
+
+Check if a file or directory exists (sync).
+
+### exists
+
+```ts
+async function exists(targetPath: string): Promise<boolean>
+```
+
+Check if a file or directory exists (async).
+
+## Directory Creation
+
+### mkdirSync
+
+```ts
+function mkdirSync(targetPath: string): void
+```
+
+Create a directory recursively (sync).
+
+### mkdir
+
+```ts
+async function mkdir(targetPath: string): Promise<void>
+```
+
+Create a directory recursively (async).
+
+## Removal
+
+### rmSync
+
+```ts
+function rmSync(targetPath: string): void
+```
+
+Remove a file or directory (sync). No retry -- fails immediately on error.
+
+### rm
+
+```ts
+async function rm(targetPath: string): Promise<void>
+```
+
+Remove a file or directory (async). Retries up to 6 times with 500ms delay for transient errors (e.g., file locks).
+
+## Copy
+
+### copySync
+
+```ts
+function copySync(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): void
+```
+
+Copy a file or directory (sync). If `sourcePath` does not exist, returns silently. Directories are copied recursively. An optional filter function controls which children are included.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sourcePath` | `string` | Source path to copy |
+| `targetPath` | `string` | Destination path |
+| `filter` | `(absolutePath: string) => boolean` | Optional filter applied to all children (not the root). Return `true` to include. If a directory returns `false`, it and all contents are skipped. |
+
+### copy
+
+```ts
+async function copy(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): Promise<void>
+```
+
+Copy a file or directory (async). Same behavior as `copySync`.
+
+## File Reading
+
+### readSync
+
+```ts
+function readSync(targetPath: string): string
+```
+
+Read a file as a UTF-8 string (sync).
+
+### read
+
+```ts
+async function read(targetPath: string): Promise<string>
+```
+
+Read a file as a UTF-8 string (async).
+
+### readBufferSync
+
+```ts
+function readBufferSync(targetPath: string): Buffer
+```
+
+Read a file as a Buffer (sync).
+
+### readBuffer
+
+```ts
+async function readBuffer(targetPath: string): Promise<Buffer>
+```
+
+Read a file as a Buffer (async).
+
+### readJsonSync
+
+```ts
+function readJsonSync<TData = unknown>(targetPath: string): TData
+```
+
+Read and parse a JSON file using `JsonConvert` (sync). 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 `JsonConvert` (async). On parse failure, the error message includes a preview of the file contents.
+
+## File Writing
+
+### writeSync
+
+```ts
+function writeSync(targetPath: string, data: string | Uint8Array): void
+```
+
+Write data to a file (sync). Parent directories are created automatically. Uses `flush: true`.
+
+### write
+
+```ts
+async function write(targetPath: string, data: string | Uint8Array): Promise<void>
+```
+
+Write data to a file (async). Parent directories are created automatically. Uses `flush: true`.
+
+### writeJsonSync
+
+```ts
+function writeJsonSync(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): void
+```
+
+Write data as a JSON file using `JsonConvert` (sync).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | `string` | Target file path |
+| `data` | `unknown` | Data to serialize |
+| `options.replacer` | `function` | Custom JSON replacer |
+| `options.space` | `string \| number` | Indentation |
+
+### writeJson
+
+```ts
+async function writeJson(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): Promise<void>
+```
+
+Write data as a JSON file using `JsonConvert` (async). Same options as `writeJsonSync`.
+
+## Directory Reading
+
+### readdirSync
+
+```ts
+function readdirSync(targetPath: string): string[]
+```
+
+List the contents of a directory (sync). Returns entry names (not full paths).
+
+### readdir
+
+```ts
+async function readdir(targetPath: string): Promise<string[]>
+```
+
+List the contents of a directory (async). Returns entry names (not full paths).
+
+## File Stats
+
+### statSync
+
+```ts
+function statSync(targetPath: string): fs.Stats
+```
+
+Get file/directory stats, following symlinks (sync).
+
+### stat
+
+```ts
+async function stat(targetPath: string): Promise<fs.Stats>
+```
+
+Get file/directory stats, following symlinks (async).
+
+### lstatSync
+
+```ts
+function lstatSync(targetPath: string): fs.Stats
+```
+
+Get file/directory stats without following symlinks (sync).
+
+### lstat
+
+```ts
+async function lstat(targetPath: string): Promise<fs.Stats>
+```
+
+Get file/directory stats without following symlinks (async).
+
+## Glob
+
+### globSync
+
+```ts
+function globSync(pattern: string, options?: GlobOptions): string[]
+```
+
+Search files by glob pattern (sync). Returns absolute paths.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pattern` | `string` | Glob pattern (e.g., `"**/*.ts"`) |
+| `options` | `GlobOptions` | Options passed to the `glob` library |
+
+### glob
+
+```ts
+async function glob(pattern: string, options?: GlobOptions): Promise<string[]>
+```
+
+Search files by glob pattern (async). Returns absolute paths.
+
+## Utilities
+
+### clearEmptyDirectory
+
+```ts
+async function clearEmptyDirectory(dirPath: string): Promise<void>
+```
+
+Recursively find and remove empty directories under a given path (async). When all subdirectories are removed and a parent becomes empty, it is also removed.
+
+### findAllParentChildPathsSync
+
+```ts
+function findAllParentChildPathsSync(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): string[]
+```
+
+Walk from `fromPath` upward toward the filesystem root, running a glob pattern at each level and collecting all matches (sync).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `childGlob` | `string` | Glob pattern to search at each directory level |
+| `fromPath` | `string` | Starting path |
+| `rootPath` | `string` | Optional stop path (must be an ancestor of `fromPath`) |
+
+### findAllParentChildPaths
+
+```ts
+async function findAllParentChildPaths(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): Promise<string[]>
+```
+
+Same as `findAllParentChildPathsSync` but asynchronous.

package/docs/pathx.md

@@ -0,0 +1,122 @@
+# pathx
+
+Namespace of path manipulation utilities. Provides normalized path types, POSIX conversion, and directory-based filtering.
+
+Imported as:
+```typescript
+import { pathx } from "@simplysm/core-node";
+```
+
+## Types
+
+### NormPath
+
+```ts
+type NormPath = string & { [NORM]: never }
+```
+
+Branded string type representing a normalized, resolved absolute path. Can only be created via `norm()`.
+
+## Functions
+
+### posix
+
+```ts
+function posix(...args: string[]): string
+```
+
+Convert a path to POSIX style (backslashes replaced with forward slashes). Accepts multiple segments which are joined with `path.join`.
+
+```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 parent directory of a file path. The file must be inside `fromDirectory`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | `string` | File path to transform |
+| `fromDirectory` | `string` | Original parent directory |
+| `toDirectory` | `string` | New parent directory |
+
+**Throws:** `ArgumentError` if `filePath` is not inside `fromDirectory`.
+
+```ts
+pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x");
+// "/x/b/c.txt"
+```
+
+### basenameWithoutExt
+
+```ts
+function basenameWithoutExt(filePath: string): string
+```
+
+Get the filename without its extension (last extension only).
+
+```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 a `NormPath` (absolute, platform-native separators).
+
+```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 a list of file paths to only include those under the specified target directories. If `targets` is empty, all files are returned.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `files` | `string[]` | Absolute file paths to filter (should be under `cwd`) |
+| `targets` | `string[]` | Target directory paths relative to `cwd` (POSIX style recommended) |
+| `cwd` | `string` | Current working directory (absolute path) |
+
+```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
+
+Type-safe worker thread abstraction built on Node.js `worker_threads`. Provides a Proxy-based API where worker methods are called as if they were local async functions.
+
+```ts
+import { Worker, createWorker } from "@simplysm/core-node";
+import type {
+  WorkerModule,
+  PromisifyMethods,
+  WorkerProxy,
+  WorkerRequest,
+  WorkerResponse,
+} from "@simplysm/core-node";
+```
+
+## Types
+
+### WorkerModule
+
+```ts
+interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+```
+
+Type structure that `createWorker()` returns. Used for type inference in `Worker.create<typeof import("./worker")>()`.
+
+| 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;
+}
+```
+
+Mapped type that wraps all method return types with `Promise<Awaited<R>>`. Worker methods always return promises because they communicate via `postMessage`.
+
+### 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 type returned by `Worker.create()`. Combines promisified methods with event subscription and termination.
+
+| Method | Description |
+|--------|-------------|
+| `on(event, listener)` | Register an event listener |
+| `off(event, listener)` | Remove an event listener |
+| `terminate()` | Terminate the worker thread |
+
+### WorkerRequest
+
+```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
+
+```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. Discriminated union on `type`.
+
+| 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
+
+Static 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 run through `tsx`. In production (`.js` files), the worker is created directly.
+
+**Returns:** `WorkerProxy<TModule>` -- Proxy object supporting direct method calls, `on()`, `off()`, and `terminate()`.
+
+## createWorker
+
+```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;
+}
+```
+
+Factory function used inside the worker thread file. Registers method handlers and sets up the message protocol. Returns a sender object for emitting events back 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:** `SdError` if not running in a worker thread (no `parentPort`).
+
+## 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.5",
   "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.5"
   },
   "devDependencies": {
-    "@types/node": "^20.14.8"
+    "@types/node": "^20.19.37"
   }
 }