@lingxia/rong 0.0.1

package/src/console.ts

@@ -0,0 +1,53 @@
+/**
+ * Console module type definitions
+ * Corresponds to: modules/rong_console
+ *
+ * Note: console is a global object provided by the runtime.
+ * This module extends the standard Web Console API.
+ */
+
+export interface Console {
+  /** Log messages to stdout */
+  log(...args: any[]): void;
+
+  /** Log error messages to stderr */
+  error(...args: any[]): void;
+
+  /** Log warning messages to stderr */
+  warn(...args: any[]): void;
+
+  /** Log informational messages to stdout */
+  info(...args: any[]): void;
+
+  /** Log debug messages to stdout */
+  debug(...args: any[]): void;
+
+  /** Clear the console */
+  clear(): void;
+}
+
+export interface ConsoleConstructor {
+  new(): Console;
+  prototype: Console;
+}
+
+// Note: console is a global object provided by the runtime
+// The standard Web Console API is available globally
+// This module documents Rong-specific console features
+
+/**
+ * Rong console supports format strings in console.log():
+ * - %s - String substitution
+ * - %d, %i - Integer substitution
+ * - %f - Float substitution
+ * - %o - Object inspection
+ *
+ * Example:
+ * console.log("Name: %s, Age: %d", "Alice", 30);
+ */
+
+declare global {
+  const Console: ConsoleConstructor;
+}
+
+export {};

package/src/encoding.ts

@@ -0,0 +1,10 @@
+/**
+ * Encoding module type definitions
+ * Corresponds to: modules/rong_encoding
+ *
+ * Note: TextEncoder and TextDecoder are provided by the global environment
+ * and match the Web API specification. No custom type definitions needed.
+ * These types are available globally when "DOM" is included in tsconfig.json lib.
+ */
+
+export {};

package/src/error.ts

@@ -0,0 +1,149 @@
+/**
+ * Error type definitions for Rong runtime
+ *
+ * Rong can throw:
+ * - standard JS `Error` objects (including `TypeError`, `RangeError`, etc.)
+ * - `DOMException` instances for Abort-related errors (e.g. `AbortError`)
+ *
+ * This module provides type guards and utilities for error handling.
+ */
+
+/**
+ * Common error names used throughout the Rong runtime (as `error.name`).
+ */
+export type RongErrorName =
+  | 'Error'
+  | 'TypeError'
+  | 'RangeError'
+  | 'ReferenceError'
+  | 'AbortError'
+  | 'NetworkError';
+
+/**
+ * Base error interface for Rong runtime errors.
+ */
+export interface RongError extends Error {
+  /** Error name identifying the error type */
+  readonly name: RongErrorName;
+
+  /** Human-readable error message */
+  readonly message: string;
+
+  /** Stable Rong error code (e.g. "E_IO", "E_TIMEOUT", ...) when available */
+  readonly code?: string;
+
+  /** Optional structured error data when provided by the runtime */
+  readonly data?: unknown;
+
+  /** Stack trace (if available) */
+  readonly stack?: string;
+}
+
+/**
+ * Error thrown when an operation is aborted via AbortSignal.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 1000);
+ *
+ * try {
+ *   await Rong.readTextFile('/large-file.txt', {
+ *     signal: controller.signal
+ *   });
+ * } catch (error) {
+ *   if (isAbortError(error)) {
+ *     console.log('Operation cancelled');
+ *   }
+ * }
+ * ```
+ */
+export interface AbortError extends RongError {
+  readonly name: 'AbortError';
+}
+
+export interface NetworkError extends RongError {
+  readonly name: 'NetworkError';
+}
+
+// ==================== Type Guards ====================
+
+/**
+ * Type guard to check if an error is a Rong runtime error.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a RongError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await Rong.readTextFile('/file.txt');
+ * } catch (error) {
+ *   if (isRongError(error)) {
+ *     console.error(`Rong error [${error.name}]: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export function isRongError(error: unknown): error is RongError {
+  return (error instanceof Error || error instanceof DOMException) &&
+    typeof (error as { name?: unknown }).name === 'string';
+}
+
+/**
+ * Type guard to check if an error is an AbortError.
+ */
+export function isAbortError(error: unknown): error is AbortError {
+  return (error instanceof Error || error instanceof DOMException) &&
+    (error as { name?: unknown }).name === 'AbortError';
+}
+
+/**
+ * Type guard to check if an error is a NetworkError.
+ */
+export function isNetworkError(error: unknown): error is NetworkError {
+  return (error instanceof Error || error instanceof DOMException) &&
+    (error as { name?: unknown }).name === 'NetworkError';
+}
+
+// ==================== Utility Functions ====================
+
+/**
+ * Get a human-readable error message from any error.
+ *
+ * @param error - The error to format
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   console.error(formatError(error));
+ * }
+ * ```
+ */
+export function formatError(error: unknown): string {
+  if (isRongError(error)) {
+    const code = error.code ? ` ${error.code}` : '';
+    return `[${error.name}${code}] ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Assert that a value is a RongError, throwing if not.
+ *
+ * @param error - The value to check
+ * @throws {TypeError} If the value is not a RongError
+ */
+export function assertRongError(error: unknown): asserts error is RongError {
+  if (!isRongError(error)) {
+    throw new TypeError('Expected RongError');
+  }
+}
+
+export {};

package/src/event.ts

@@ -0,0 +1,128 @@
+/**
+ * Event module type definitions
+ * Corresponds to: modules/rong_event
+ */
+
+export interface EventOptions {
+  /** Whether the event bubbles */
+  bubbles?: boolean;
+  /** Whether the event can be cancelled */
+  cancelable?: boolean;
+  /** Whether the event can cross shadow DOM boundaries */
+  composed?: boolean;
+}
+
+export interface Event {
+  /** Event type name */
+  readonly type: string;
+
+  /** Whether the event bubbles */
+  readonly bubbles: boolean;
+
+  /** Whether the event can be cancelled */
+  readonly cancelable: boolean;
+
+  /** Whether the event can cross shadow DOM boundaries */
+  readonly composed: boolean;
+}
+
+export interface EventConstructor {
+  new(type: string, options?: EventOptions): Event;
+  prototype: Event;
+}
+
+export interface CustomEventOptions extends EventOptions {
+  /** Custom data associated with the event */
+  detail?: any;
+}
+
+export interface CustomEvent extends Event {
+  /** Custom data associated with the event */
+  readonly detail: any;
+}
+
+export interface CustomEventConstructor {
+  new(type: string, options?: CustomEventOptions): CustomEvent;
+  prototype: CustomEvent;
+}
+
+export type EventListener = (event: Event) => void;
+
+export interface AddEventListenerOptions {
+  /** Remove listener after first invocation */
+  once?: boolean;
+  /** Use capture phase */
+  capture?: boolean;
+  /** Listener is passive (won't call preventDefault) */
+  passive?: boolean;
+}
+
+export interface EventTarget {
+  /** Add event listener (Web standard) */
+  addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+
+  /** Remove event listener (Web standard) */
+  removeEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+
+  /** Dispatch event (Web standard) */
+  dispatchEvent(event: Event): boolean;
+}
+
+export interface EventTargetConstructor {
+  new(): EventTarget;
+  prototype: EventTarget;
+}
+
+export type EventName = string | symbol;
+export type EventEmitterListener = (...args: any[]) => void;
+
+export interface EventEmitter extends EventTarget {
+  /** Add event listener (Node.js style) */
+  on(eventName: EventName, listener: EventEmitterListener): this;
+
+  /** Add one-time event listener */
+  once(eventName: EventName, listener: EventEmitterListener): this;
+
+  /** Remove event listener */
+  off(eventName: EventName, listener: EventEmitterListener): this;
+
+  /** Remove event listener (alias for off) */
+  removeListener(eventName: EventName, listener: EventEmitterListener): this;
+
+  /** Remove all listeners for an event */
+  removeAllListeners(eventName?: EventName): this;
+
+  /** Add listener at the beginning of the listeners array */
+  prependListener(eventName: EventName, listener: EventEmitterListener): this;
+
+  /** Add one-time listener at the beginning of the listeners array */
+  prependOnceListener(eventName: EventName, listener: EventEmitterListener): this;
+
+  /** Emit an event */
+  emit(eventName: EventName, ...args: any[]): boolean;
+
+  /** Get array of registered event names */
+  eventNames(): EventName[];
+
+  /** Set maximum number of listeners per event (default: 10) */
+  setMaxListeners(n: number): this;
+
+  /** Get maximum number of listeners per event */
+  getMaxListeners(): number;
+
+  /** Get number of listeners for an event, optionally filtered by a specific listener */
+  listenerCount(eventName: EventName, listener?: EventEmitterListener): number;
+}
+
+export interface EventEmitterConstructor {
+  new(): EventEmitter;
+  prototype: EventEmitter;
+}
+
+// Note: Event, CustomEvent, and EventTarget are provided by the global environment (Web API)
+// EventEmitter is a Rong-specific Node.js-style event emitter
+declare global {
+  const EventEmitter: EventEmitterConstructor;
+}
+
+export {};

package/src/exception.ts

@@ -0,0 +1,77 @@
+/**
+ * Exception module type definitions
+ * Corresponds to: modules/rong_exception
+ */
+
+export type DOMExceptionName =
+  | 'IndexSizeError'
+  | 'DOMStringSizeError'
+  | 'HierarchyRequestError'
+  | 'InvalidCharacterError'
+  | 'NoDataAllowedError'
+  | 'NoModificationAllowedError'
+  | 'NotFoundError'
+  | 'NotSupportedError'
+  | 'InUseAttributeError'
+  | 'InvalidStateError'
+  | 'SyntaxError'
+  | 'InvalidModificationError'
+  | 'NamespaceError'
+  | 'InvalidAccessError'
+  | 'ValidationError'
+  | 'TypeMismatchError'
+  | 'SecurityError'
+  | 'NetworkError'
+  | 'AbortError'
+  | 'URLMismatchError'
+  | 'QuotaExceededError'
+  | 'TimeoutError'
+  | 'InvalidNodeTypeError'
+  | 'DataCloneError'
+  | 'Error'
+  // Node.js-style constant names accepted by Rong's DOMException implementation
+  | 'INDEX_SIZE_ERR'
+  | 'DOMSTRING_SIZE_ERR'
+  | 'HIERARCHY_REQUEST_ERR'
+  | 'INVALID_CHARACTER_ERR'
+  | 'NO_DATA_ALLOWED_ERR'
+  | 'NO_MODIFICATION_ALLOWED_ERR'
+  | 'NOT_FOUND_ERR'
+  | 'NOT_SUPPORTED_ERR'
+  | 'INUSE_ATTRIBUTE_ERR'
+  | 'INVALID_STATE_ERR'
+  | 'SYNTAX_ERR'
+  | 'INVALID_MODIFICATION_ERR'
+  | 'NAMESPACE_ERR'
+  | 'INVALID_ACCESS_ERR'
+  | 'VALIDATION_ERR'
+  | 'TYPE_MISMATCH_ERR'
+  | 'SECURITY_ERR'
+  | 'NETWORK_ERR'
+  | 'ABORT_ERR'
+  | 'URL_MISMATCH_ERR'
+  | 'QUOTA_EXCEEDED_ERR'
+  | 'TIMEOUT_ERR'
+  | 'INVALID_NODE_TYPE_ERR'
+  | 'DATA_CLONE_ERR'
+  | 'ERROR';
+
+export interface DOMException extends Error {
+  /** Error name */
+  readonly name: string;
+
+  /** Error message */
+  readonly message: string;
+
+  /** Stack trace (currently returns "NotImplemented") */
+  readonly stack: string;
+}
+
+export interface DOMExceptionConstructor {
+  new(message?: string, name?: DOMExceptionName): DOMException;
+  prototype: DOMException;
+}
+
+// Note: DOMException is provided by the global environment (Web API)
+// These type definitions are for reference and extend the standard Web API
+export {};