@lingxia/rong 0.2.0 → 0.3.0

package/README.md

@@ -9,12 +9,11 @@ TypeScript type definitions for the Rong JavaScript runtime (globals injected by
 
 ## Runtime Export Map (high level)
 
-Rong injects a small set of globals:
+- `Rong` namespace: file system, storage, runtime metadata, command APIs, timer helpers, compression helpers, and host constructors such as `RedisClient`, `S3Client`, `SQLite`, and `SSE`
+- Globals added by Rong modules include `fetch`, `assert`, `atob`, `btoa`, `Worker`, `setTimeout`, `clearTimeout`, `setInterval`, and `clearInterval`
+- Additional Web-standard globals such as `Request`, `Response`, `Headers`, `FormData`, `URL`, `ReadableStream`, `WritableStream`, `Blob`, `File`, `AbortController`, and `DOMException` are also provided when the corresponding runtime modules are enabled
 
-- `Rong` namespace: file system + storage
-- Globals: `process`, `child_process`, `path`, `fetch`, `timers`, `assert`, `atob`, `btoa`
-
-Rong also implements/extends a subset of Web APIs; the type package relies on TypeScript’s DOM libs for base types like `URL`, `ReadableStream`, `AbortController`, etc.
+The type package relies on TypeScript’s DOM libs for shared Web API base types.
 
 ## Installation
 
@@ -36,12 +35,15 @@ Add to your `tsconfig.json`:
 
 Notes:
 
-- This enables global typings; you should not `import` runtime modules like `'child_process'` or `'http'` (those are Rong globals, not Node modules).
+- This enables global typings; you should not `import` runtime modules like `'http'` (those are Rong globals, not Node modules).
 - Ensure your `tsconfig.json` `lib` includes `"DOM"` if you want DOM globals (e.g. `URL`, `ReadableStream`) to be typed.
+- `Worker` uses the DOM global type name. The package exports `RongWorker`/`RongWorkerMessageEvent`/`RongWorkerErrorEvent` for the precise Rong subset when you want stricter annotations.
+- Rong’s runtime `Storage` constructor intentionally is not redeclared globally in the type package, because the DOM lib already owns the global `Storage` name. Use the exported `Storage`/`StorageConstructor` types as local annotations when needed.
+- The package only supports the root export `@lingxia/rong`; `src/*` and `dist/*` are not public import paths.
 
 ## Accuracy notes (common gotchas)
 
-- Storage is not `localStorage`-compatible. Use `await Rong.storage.open(path)` or `new Rong.Storage(path)`, then `set/get/delete/clear/list/info`.
+- Storage is not `localStorage`-compatible. The standard runtime exposes `new Storage(path, options?)`; embedders may also inject a preconfigured `storage` instance, but that is not part of the default runtime surface.
 - Directory listing is `Rong.readDir(...)` (async iterator), not `Rong.readdir(...)`.
 - HTTP is the global `fetch(...)` API. There is no `http` namespace and no `download` JS API.
 

package/dist/command.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Command execution APIs mounted on the Rong namespace.
+ * Corresponds to: modules/rong_command
+ */
+export type RongSpawnStdio = 'pipe' | 'ignore' | 'inherit';
+export type RongEnvMap = Record<string, string | undefined>;
+export interface RongSpawnOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    shell?: boolean;
+    stdin?: 'pipe' | string | ArrayBuffer | ArrayBufferView | null;
+    stdout?: RongSpawnStdio;
+    stderr?: RongSpawnStdio;
+    timeout?: number;
+    killSignal?: string | number;
+    signal?: AbortSignal;
+    onExit?(subprocess: RongSubprocess, exitCode: number | null, signalCode: number | null, error?: unknown): void | Promise<void>;
+}
+export interface RongSpawnOptionsWithCmd extends RongSpawnOptions {
+    cmd: string[];
+}
+export interface RongSyncSubprocess {
+    readonly exitCode: number | null;
+    readonly success: boolean;
+    readonly signalCode: number | null;
+    readonly stdout: Uint8Array;
+    readonly stderr: Uint8Array;
+}
+export interface RongReadableProcessStream extends ReadableStream<Uint8Array> {
+    bytes(): Promise<Uint8Array>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    blob(): Promise<Blob>;
+    lines(): AsyncIterableIterator<string>;
+}
+export interface RongOutputHandle {
+    write(chunk: string | ArrayBuffer | ArrayBufferView): void;
+    flush(): void;
+}
+export interface RongWritableProcessStream extends WritableStream<Uint8Array> {
+    write(chunk: string | ArrayBuffer | ArrayBufferView): Promise<this>;
+    flush(): Promise<void>;
+    end(): Promise<void>;
+}
+export interface RongSubprocess {
+    readonly pid: number | null;
+    readonly exitCode: number | null;
+    readonly signalCode: number | null;
+    readonly killed: boolean;
+    readonly success: boolean;
+    readonly exited: Promise<number | null>;
+    stdin: RongWritableProcessStream | null;
+    stdout: RongReadableProcessStream | null;
+    stderr: RongReadableProcessStream | null;
+    kill(signal?: string | number): boolean;
+    wait(): Promise<number | null>;
+    unref(): void;
+}
+export interface RongShellResult {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    exitCode: number | null;
+    success: boolean;
+}
+export interface RongShellCommand extends PromiseLike<RongShellResult> {
+    cwd(path: string): RongShellCommand;
+    env(values: Record<string, string | undefined>): RongShellCommand;
+    quiet(): RongShellCommand;
+    nothrow(): RongShellCommand;
+    throws(value?: boolean): RongShellCommand;
+    run(): Promise<RongShellResult>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    blob(): Promise<Blob>;
+    lines(): AsyncIterableIterator<string>;
+}
+export interface RongShellTag {
+    (strings: TemplateStringsArray, ...values: unknown[]): RongShellCommand;
+    (command: string): RongShellCommand;
+    cwd(path?: string): string | RongShellTag | undefined;
+    env(values?: Record<string, string | undefined>): Record<string, string | undefined> | RongShellTag | undefined;
+    throws(value?: boolean): RongShellTag;
+    nothrow(): RongShellTag;
+    quiet(): RongShellTag;
+    escape(value: unknown): string;
+}
+export interface RongShellError extends Error {
+    command: string;
+    exitCode: number | null;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,IAAI,CAAC;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,CACL,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,KAAK,CAAC,EAAE,OAAO,GACd,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,WAAW,yBAA0B,SAAQ,cAAc,CAAC,UAAU,CAAC;IAC3E,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,IAAI,CAAC;IAC3D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,yBAA0B,SAAQ,cAAc,CAAC,UAAU,CAAC;IAC3E,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,KAAK,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACxC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACxC,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW,CAAC,eAAe,CAAC;IACpE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACpC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,gBAAgB,CAAC;IAClE,KAAK,IAAI,gBAAgB,CAAC;IAC1B,OAAO,IAAI,gBAAgB,CAAC;IAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAC1C,GAAG,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IAChC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;IACxE,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACpC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IACtD,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,YAAY,GAAG,SAAS,CAAC;IAChH,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACtC,OAAO,IAAI,YAAY,CAAC;IACxB,KAAK,IAAI,YAAY,CAAC;IACtB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,cAAe,SAAQ,KAAK;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;CACpB"}

package/dist/command.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Command execution APIs mounted on the Rong namespace.
+ * Corresponds to: modules/rong_command
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/compression.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compression APIs mounted on the Rong namespace.
+ * Corresponds to: modules/rong_compression
+ */
+export type RongCompressionInput = ArrayBuffer | ArrayBufferView;
+export interface RongZstdCompressOptions {
+    level?: number;
+}
+export interface RongGzipCompressOptions {
+    level?: number;
+}
+//# sourceMappingURL=compression.d.ts.map

package/dist/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../src/compression.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,eAAe,CAAC;AAEjE,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/compression.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Compression APIs mounted on the Rong namespace.
+ * Corresponds to: modules/rong_compression
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/console.d.ts

@@ -16,13 +16,29 @@ export interface Console {
     info(...args: any[]): void;
     /** Log debug messages to stdout */
     debug(...args: any[]): void;
+    /** Log assertion failures to stderr */
+    assert(condition?: any, ...args: any[]): void;
+    /** Inspect a value with optional depth and length limits */
+    dir(value?: any, options?: {
+        depth?: number;
+        maxArrayLength?: number;
+        maxObjectKeys?: number;
+    }): void;
+    /** Log a stack trace */
+    trace(...args: any[]): void;
+    /** Start a named timer */
+    time(label?: string): void;
+    /** Log the elapsed time for a timer without stopping it */
+    timeLog(label?: string, ...args: any[]): void;
+    /** Log the elapsed time for a timer and stop it */
+    timeEnd(label?: string): void;
+    /** Increment and log a named counter */
+    count(label?: string): void;
+    /** Reset a named counter */
+    countReset(label?: string): void;
     /** Clear the console */
     clear(): void;
 }
-export interface ConsoleConstructor {
-    new (): Console;
-    prototype: Console;
-}
 /**
  * Rong console supports format strings in console.log():
  * - %s - String substitution
@@ -33,8 +49,5 @@ export interface ConsoleConstructor {
  * Example:
  * console.log("Name: %s, Age: %d", "Alice", 30);
  */
-declare global {
-    const Console: ConsoleConstructor;
-}
 export {};
 //# sourceMappingURL=console.d.ts.map

package/dist/console.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../src/console.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,OAAO;IACtB,6BAA6B;IAC7B,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE1B,mCAAmC;IACnC,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE5B,qCAAqC;IACrC,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE3B,2CAA2C;IAC3C,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE3B,mCAAmC;IACnC,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE5B,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAO,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD;;;;;;;;;GASG;AAEH,OAAO,CAAC,MAAM,CAAC;IACb,MAAM,OAAO,EAAE,kBAAkB,CAAC;CACnC;AAED,OAAO,EAAE,CAAC"}
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../src/console.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,OAAO;IACtB,6BAA6B;IAC7B,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE1B,mCAAmC;IACnC,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE5B,qCAAqC;IACrC,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE3B,2CAA2C;IAC3C,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE3B,mCAAmC;IACnC,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE5B,uCAAuC;IACvC,MAAM,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE9C,4DAA4D;IAC5D,GAAG,CACD,KAAK,CAAC,EAAE,GAAG,EACX,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,IAAI,CAAC;IAER,wBAAwB;IACxB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE5B,0BAA0B;IAC1B,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,2DAA2D;IAC3D,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE9C,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,wCAAwC;IACxC,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,4BAA4B;IAC5B,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC"}

package/dist/error.d.ts

@@ -1,22 +1,37 @@
 /**
  * Error type definitions for Rong runtime
  *
- * Rong can throw:
+ * Rong can throw or reject with any JavaScript value.
+ *
+ * Common host-generated cases are:
  * - standard JS `Error` objects (including `TypeError`, `RangeError`, etc.)
- * - `DOMException` instances for Abort-related errors (e.g. `AbortError`)
+ * - `DOMException`-like objects for web-style failures (e.g. `AbortError`)
+ * - preserved JavaScript payloads from `throw <value>` / Promise rejection / abort reasons
  *
- * This module provides type guards and utilities for error handling.
+ * This module provides type guards and utilities for the error-object subset.
+ */
+/**
+ * Known error names commonly produced by Rong host APIs.
  */
+export type KnownRongErrorName = 'Error' | 'TypeError' | 'RangeError' | 'ReferenceError' | 'AbortError' | 'NetworkError' | 'SyntaxError' | 'InvalidStateError' | 'NotSupportedError' | 'TimeoutError' | 'SecurityError' | 'QuotaExceededError' | 'NotFoundError' | 'DataCloneError' | 'InvalidAccessError' | 'TypeMismatchError' | 'URLMismatchError';
 /**
- * Common error names used throughout the Rong runtime (as `error.name`).
+ * Backwards-compatible alias for the known error-name set.
  */
-export type RongErrorName = 'Error' | 'TypeError' | 'RangeError' | 'ReferenceError' | 'AbortError' | 'NetworkError';
+export type RongErrorName = KnownRongErrorName;
 /**
- * Base error interface for Rong runtime errors.
+ * Catch/reject payload from Rong.
+ *
+ * This is intentionally `unknown`: runtime code may preserve arbitrary JavaScript values.
+ */
+export type RongThrowable = unknown;
+/**
+ * Error-object shape commonly produced by Rong host APIs.
+ *
+ * Note that not every caught Rong throwable matches this interface.
  */
 export interface RongError extends Error {
     /** Error name identifying the error type */
-    readonly name: RongErrorName;
+    readonly name: string;
     /** Human-readable error message */
     readonly message: string;
     /** Stable Rong error code (e.g. "E_IO", "E_TIMEOUT", ...) when available */
@@ -35,7 +50,7 @@ export interface RongError extends Error {
  * setTimeout(() => controller.abort(), 1000);
  *
  * try {
- *   await Rong.readTextFile('/large-file.txt', {
+ *   await fetch('https://api.example.com/slow', {
  *     signal: controller.signal
  *   });
  * } catch (error) {
@@ -52,15 +67,15 @@ export interface NetworkError extends RongError {
     readonly name: 'NetworkError';
 }
 /**
- * Type guard to check if an error is a Rong runtime error.
+ * Type guard to check if a caught value is an Error-like object from Rong.
  *
  * @param error - The error to check
- * @returns true if the error is a RongError
+ * @returns true if the value behaves like a RongError object
  *
  * @example
  * ```typescript
  * try {
- *   await Rong.readTextFile('/file.txt');
+ *   await Rong.file('/file.txt').text();
  * } catch (error) {
  *   if (isRongError(error)) {
  *     console.error(`Rong error [${error.name}]: ${error.message}`);
@@ -77,6 +92,18 @@ export declare function isAbortError(error: unknown): error is AbortError;
  * Type guard to check if an error is a NetworkError.
  */
 export declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Returns the `.name` of an Error-like throwable when present.
+ */
+export declare function getErrorName(error: unknown): string | undefined;
+/**
+ * Returns the stable Rong `.code` when present on an Error-like throwable.
+ */
+export declare function getErrorCode(error: unknown): string | undefined;
+/**
+ * Get a human-readable message from any throwable value.
+ */
+export declare function getErrorMessage(error: unknown): string;
 /**
  * Get a human-readable error message from any error.
  *
@@ -94,10 +121,10 @@ export declare function isNetworkError(error: unknown): error is NetworkError;
  */
 export declare function formatError(error: unknown): string;
 /**
- * Assert that a value is a RongError, throwing if not.
+ * Assert that a value is a RongError-like object, throwing if not.
  *
  * @param error - The value to check
- * @throws {TypeError} If the value is not a RongError
+ * @throws {TypeError} If the value is not a RongError-like object
  */
 export declare function assertRongError(error: unknown): asserts error is RongError;
 export {};

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,OAAO,GACP,WAAW,GACX,YAAY,GACZ,gBAAgB,GAChB,YAAY,GACZ,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAG9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAGhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAGpE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CASlD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAI1E;AAED,OAAO,EAAE,CAAC"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,WAAW,GACX,YAAY,GACZ,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,aAAa,GACb,mBAAmB,GACnB,mBAAmB,GACnB,cAAc,GACd,eAAe,GACf,oBAAoB,GACpB,eAAe,GACf,gBAAgB,GAChB,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,CAAC;AAEvB;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAI9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWlD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAI1E;AAED,OAAO,EAAE,CAAC"}

package/dist/error.js

@@ -2,25 +2,40 @@
 /**
  * Error type definitions for Rong runtime
  *
- * Rong can throw:
+ * Rong can throw or reject with any JavaScript value.
+ *
+ * Common host-generated cases are:
  * - standard JS `Error` objects (including `TypeError`, `RangeError`, etc.)
- * - `DOMException` instances for Abort-related errors (e.g. `AbortError`)
+ * - `DOMException`-like objects for web-style failures (e.g. `AbortError`)
+ * - preserved JavaScript payloads from `throw <value>` / Promise rejection / abort reasons
  *
- * This module provides type guards and utilities for error handling.
+ * This module provides type guards and utilities for the error-object subset.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertRongError = exports.formatError = exports.isNetworkError = exports.isAbortError = exports.isRongError = void 0;
-// ==================== Type Guards ====================
+exports.isRongError = isRongError;
+exports.isAbortError = isAbortError;
+exports.isNetworkError = isNetworkError;
+exports.getErrorName = getErrorName;
+exports.getErrorCode = getErrorCode;
+exports.getErrorMessage = getErrorMessage;
+exports.formatError = formatError;
+exports.assertRongError = assertRongError;
+function getField(error, key) {
+    if ((typeof error === 'object' && error !== null) || typeof error === 'function') {
+        return error[key];
+    }
+    return undefined;
+}
 /**
- * Type guard to check if an error is a Rong runtime error.
+ * Type guard to check if a caught value is an Error-like object from Rong.
  *
  * @param error - The error to check
- * @returns true if the error is a RongError
+ * @returns true if the value behaves like a RongError object
  *
  * @example
  * ```typescript
  * try {
- *   await Rong.readTextFile('/file.txt');
+ *   await Rong.file('/file.txt').text();
  * } catch (error) {
  *   if (isRongError(error)) {
  *     console.error(`Rong error [${error.name}]: ${error.message}`);
@@ -30,26 +45,48 @@ exports.assertRongError = exports.formatError = exports.isNetworkError = exports
  */
 function isRongError(error) {
     return (error instanceof Error || error instanceof DOMException) &&
-        typeof error.name === 'string';
+        typeof getField(error, 'name') === 'string' &&
+        typeof getField(error, 'message') === 'string';
 }
-exports.isRongError = isRongError;
 /**
  * Type guard to check if an error is an AbortError.
  */
 function isAbortError(error) {
-    return (error instanceof Error || error instanceof DOMException) &&
-        error.name === 'AbortError';
+    return isRongError(error) && error.name === 'AbortError';
 }
-exports.isAbortError = isAbortError;
 /**
  * Type guard to check if an error is a NetworkError.
  */
 function isNetworkError(error) {
-    return (error instanceof Error || error instanceof DOMException) &&
-        error.name === 'NetworkError';
+    return isRongError(error) && error.name === 'NetworkError';
+}
+/**
+ * Returns the `.name` of an Error-like throwable when present.
+ */
+function getErrorName(error) {
+    const name = getField(error, 'name');
+    return typeof name === 'string' ? name : undefined;
+}
+/**
+ * Returns the stable Rong `.code` when present on an Error-like throwable.
+ */
+function getErrorCode(error) {
+    const code = getField(error, 'code');
+    return typeof code === 'string' ? code : undefined;
+}
+/**
+ * Get a human-readable message from any throwable value.
+ */
+function getErrorMessage(error) {
+    if (typeof error === 'string') {
+        return error;
+    }
+    const message = getField(error, 'message');
+    if (typeof message === 'string') {
+        return message;
+    }
+    return String(error);
 }
-exports.isNetworkError = isNetworkError;
-// ==================== Utility Functions ====================
 /**
  * Get a human-readable error message from any error.
  *
@@ -66,25 +103,23 @@ exports.isNetworkError = isNetworkError;
  * ```
  */
 function formatError(error) {
-    if (isRongError(error)) {
-        const code = error.code ? ` ${error.code}` : '';
-        return `[${error.name}${code}] ${error.message}`;
-    }
-    if (error instanceof Error) {
-        return error.message;
+    const name = getErrorName(error);
+    const code = getErrorCode(error);
+    const message = getErrorMessage(error);
+    if (name) {
+        const formattedCode = code ? ` ${code}` : '';
+        return `[${name}${formattedCode}] ${message}`;
     }
-    return String(error);
+    return message;
 }
-exports.formatError = formatError;
 /**
- * Assert that a value is a RongError, throwing if not.
+ * Assert that a value is a RongError-like object, throwing if not.
  *
  * @param error - The value to check
- * @throws {TypeError} If the value is not a RongError
+ * @throws {TypeError} If the value is not a RongError-like object
  */
 function assertRongError(error) {
     if (!isRongError(error)) {
         throw new TypeError('Expected RongError');
     }
 }
-exports.assertRongError = assertRongError;