@serveryyswys/node.operit 0.1.2 → 0.1.3

package/NOTICE

@@ -0,0 +1,17 @@
+@serveryyswys/node.operit
+Copyright 2026 serveryyswys
+
+This product includes software developed by serveryyswys
+(https://www.serveryyswys.top/).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -299,4 +299,14 @@ globalThis.Buffer  = require('<rel>/node_modules/@serveryyswys/node.operit/dist/
     读流是"按需整块读 + 按 `highWaterMark` 切片"（**没有流式的内存特性**），`'open'` 事件参数为 `null`（无真实 fd）
   - **Java 驱动尚未在真机验证**；已知近似：`atime`/`ctime`/`birthtime` 取 `mtime`、
     `mode` 为按类型的默认值、`readdir` 不区分符号链接、fd 系列（`open`/`read`/`write`/`close`）未实现
+- `console`：**partial** —— 完整的 Node console API；**输出与 Node 逐字节对拍通过**（含 `%s`/`%d`/`%j`、
+  `assert` 只打印不抛错、`group` 缩进）。差异：不指定输出流时写 prelude console；`table` 只覆盖常用形态
+- `util/types` / `sys`：**ready** —— 分别是 `util.types` 与 `util` 的同一个对象（与 Node 一致）
+- `punycode`：**ready** —— 各方法与 Node 的 punycode 对拍一致（含 `ucs2`）
+- `stream/consumers`：**partial** —— `buffer`/`text`/`json`/`arrayBuffer` 可用；
+  `blob` 显式抛 `ONJ_UNSUPPORTED`（运行时不提供 Blob）
+- `diagnostics_channel`：**partial** —— 发布订阅完整可用；依赖 AsyncLocalStorage 的
+  `bindStore`/`unbindStore`/`runStores` 与 `tracingChannel` 显式抛 `ONJ_UNSUPPORTED`
+- `v8`：**partial** —— 堆统计字段名与 Node 一致，但取的是 **JVM 堆**；
+  `serialize`/`deserialize`/`setFlagsFromString` 等 V8 专有能力显式抛 `ONJ_UNSUPPORTED`
 - 其余见 `BUILTINS.json`

package/dist/console.d.ts

@@ -0,0 +1,60 @@
+import { WriteStreamLike } from './lib/console-types';
+declare class Console {
+    constructor(stdout?: unknown, stderr?: unknown);
+    readonly stdout: WriteStreamLike | null;
+    readonly stderr: WriteStreamLike | null;
+    readonly counts: Map<string, number>;
+    readonly timers: Map<string, number>;
+    indent: string;
+    emit(target: WriteStreamLike | null, channel: 'log' | 'info' | 'warn' | 'error', text: string): void;
+    line(...args: unknown[]): string;
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /** Node 的 console.assert 只在断言失败时输出，且不抛错。 */
+    assert(value: unknown, ...args: unknown[]): void;
+    dir(value: unknown, options?: unknown): void;
+    count(label?: string): void;
+    countReset(label?: string): void;
+    time(label?: string): void;
+    timeEnd(label?: string): void;
+    timeLog(label?: string, ...args: unknown[]): void;
+    trace(...args: unknown[]): void;
+    table(data: unknown, columns?: readonly string[]): void;
+    group(...args: unknown[]): void;
+    groupCollapsed(...args: unknown[]): void;
+    groupEnd(): void;
+    /** 非 TTY 下与 Node 一样什么都不做。 */
+    clear(): void;
+    profile(): void;
+    profileEnd(): void;
+    timeStamp(): void;
+}
+/** Node 的 require('console') 给的是实例，并把 Console 挂在它上面。 */
+declare const consoleModule: {
+    Console: typeof Console;
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    assert: (value: unknown, ...args: unknown[]) => void;
+    dir: (value: unknown, options?: unknown) => void;
+    count: (label?: string) => void;
+    countReset: (label?: string) => void;
+    time: (label?: string) => void;
+    timeEnd: (label?: string) => void;
+    timeLog: (label?: string, ...args: unknown[]) => void;
+    trace: (...args: unknown[]) => void;
+    table: (data: unknown, columns?: readonly string[]) => void;
+    group: (...args: unknown[]) => void;
+    groupCollapsed: (...args: unknown[]) => void;
+    groupEnd: () => void;
+    clear: () => void;
+    profile: () => void;
+    profileEnd: () => void;
+    timeStamp: () => void;
+};
+export = consoleModule;

package/dist/console.js

@@ -0,0 +1,193 @@
+'use strict';
+/**
+ * console。
+ *
+ * 沙箱的 prelude 已经在每个模块作用域里提供了一个 console（JsExecutionScriptBuilder.kt:53），
+ * 但它只有 log / info / warn / error 四个方法，而且是 `arguments.join(' ')` ——
+ * 也就是 `console.log('%s', 'x')` 会原样打印 "%s x"，与 Node 不同。
+ *
+ * 本模块在这之上补齐 Node 的 console API，并改用 util.format 格式化。
+ *
+ * 与 Node 的差异（都写进 BUILTINS.json）：
+ *   - 不指定输出流时走 prelude console（Node 是 process.stdout / stderr）；
+ *   - clear / profile / profileEnd / timeStamp 与 Node 在非 TTY 下一样是空操作；
+ *   - table 只实现 Node 的常用形态（对象数组 / 单对象），不做列的自动推算。
+ */
+const utilModule = require("./util");
+const hostConsole = console;
+function hasWrite(value) {
+    return typeof value === 'object' && value !== null && typeof value.write === 'function';
+}
+function nowMillis() {
+    return typeof performance === 'object' && performance !== null ? performance.now() : Date.now();
+}
+function describeTime(milliseconds) {
+    return milliseconds.toFixed(3) + 'ms';
+}
+class Console {
+    constructor(stdout, stderr) {
+        this.counts = new Map();
+        this.timers = new Map();
+        this.indent = '';
+        this.stdout = hasWrite(stdout) ? stdout : null;
+        this.stderr = hasWrite(stderr) ? stderr : null;
+    }
+    emit(target, channel, text) {
+        if (target !== null) {
+            target.write(text + '\n');
+            return;
+        }
+        hostConsole[channel](text);
+    }
+    line(...args) {
+        return this.indent + utilModule.format.apply(null, args);
+    }
+    log(...args) {
+        this.emit(this.stdout, 'log', this.line(...args));
+    }
+    info(...args) {
+        this.emit(this.stdout, 'info', this.line(...args));
+    }
+    debug(...args) {
+        this.emit(this.stdout, 'log', this.line(...args));
+    }
+    warn(...args) {
+        this.emit(this.stderr, 'warn', this.line(...args));
+    }
+    error(...args) {
+        this.emit(this.stderr, 'error', this.line(...args));
+    }
+    /** Node 的 console.assert 只在断言失败时输出，且不抛错。 */
+    assert(value, ...args) {
+        if (value) {
+            return;
+        }
+        const detail = args.length === 0 ? '' : ': ' + utilModule.format.apply(null, args);
+        this.emit(this.stderr, 'error', 'Assertion failed' + detail);
+    }
+    dir(value, options) {
+        this.emit(this.stdout, 'log', this.indent + utilModule.inspect(value, options));
+    }
+    count(label) {
+        const key = label === undefined ? 'default' : String(label);
+        const next = (this.counts.get(key) ?? 0) + 1;
+        this.counts.set(key, next);
+        this.emit(this.stdout, 'log', this.indent + key + ': ' + next);
+    }
+    countReset(label) {
+        const key = label === undefined ? 'default' : String(label);
+        this.counts.set(key, 0);
+        this.emit(this.stdout, 'log', this.indent + key + ': 0');
+    }
+    time(label) {
+        this.timers.set(label === undefined ? 'default' : String(label), nowMillis());
+    }
+    timeEnd(label) {
+        const key = label === undefined ? 'default' : String(label);
+        const started = this.timers.get(key);
+        if (started === undefined) {
+            this.emit(this.stderr, 'warn', 'Warning: No such label \'' + key + '\' for console.timeEnd()');
+            return;
+        }
+        this.timers.delete(key);
+        this.emit(this.stdout, 'log', this.indent + key + ': ' + describeTime(nowMillis() - started));
+    }
+    timeLog(label, ...args) {
+        const key = label === undefined ? 'default' : String(label);
+        const started = this.timers.get(key);
+        if (started === undefined) {
+            this.emit(this.stderr, 'warn', 'Warning: No such label \'' + key + '\' for console.timeLog()');
+            return;
+        }
+        const suffix = args.length === 0 ? '' : ' ' + utilModule.format.apply(null, args);
+        this.emit(this.stdout, 'log', this.indent + key + ': ' + describeTime(nowMillis() - started) + suffix);
+    }
+    trace(...args) {
+        const message = args.length === 0 ? 'Trace' : 'Trace: ' + utilModule.format.apply(null, args);
+        const stack = new Error(message).stack;
+        this.emit(this.stderr, 'error', this.indent + message + (stack === undefined ? '' : '\n' + stack));
+    }
+    table(data, columns) {
+        if (data === null || typeof data !== 'object') {
+            this.log(data);
+            return;
+        }
+        const rows = Array.isArray(data) ? data : [data];
+        const keys = [];
+        for (let index = 0; index < rows.length; index += 1) {
+            const row = rows[index];
+            if (row === null || typeof row !== 'object') {
+                continue;
+            }
+            const names = columns === undefined ? Object.keys(row) : columns;
+            for (let name = 0; name < names.length; name += 1) {
+                if (keys.indexOf(names[name]) < 0) {
+                    keys.push(names[name]);
+                }
+            }
+        }
+        const lines = ['┌─────────┬' + keys.map(() => '──────────').join('┬') + '┐'];
+        lines.push('│ (index) │' + keys.map((key) => ' ' + key.padEnd(8) + ' │').join(''));
+        for (let index = 0; index < rows.length; index += 1) {
+            const row = rows[index];
+            const cells = keys.map((key) => ' ' + utilModule.inspect(row === null || row === undefined ? undefined : row[key]).slice(0, 8).padEnd(8) + ' │');
+            lines.push('│ ' + String(index).padEnd(7) + ' │' + cells.join(''));
+        }
+        lines.push('└─────────┴' + keys.map(() => '──────────').join('┴') + '┘');
+        this.emit(this.stdout, 'log', this.indent + lines.join('\n' + this.indent));
+    }
+    group(...args) {
+        if (args.length > 0) {
+            this.log(...args);
+        }
+        this.indent += '  ';
+    }
+    groupCollapsed(...args) {
+        this.group(...args);
+    }
+    groupEnd() {
+        if (this.indent.length >= 2) {
+            this.indent = this.indent.slice(0, -2);
+        }
+    }
+    /** 非 TTY 下与 Node 一样什么都不做。 */
+    clear() {
+        return;
+    }
+    profile() {
+        return;
+    }
+    profileEnd() {
+        return;
+    }
+    timeStamp() {
+        return;
+    }
+}
+const consoleInstance = new Console();
+/** Node 的 require('console') 给的是实例，并把 Console 挂在它上面。 */
+const consoleModule = {
+    Console: Console,
+    log: consoleInstance.log.bind(consoleInstance),
+    info: consoleInstance.info.bind(consoleInstance),
+    debug: consoleInstance.debug.bind(consoleInstance),
+    warn: consoleInstance.warn.bind(consoleInstance),
+    error: consoleInstance.error.bind(consoleInstance),
+    assert: consoleInstance.assert.bind(consoleInstance),
+    dir: consoleInstance.dir.bind(consoleInstance),
+    count: consoleInstance.count.bind(consoleInstance),
+    countReset: consoleInstance.countReset.bind(consoleInstance),
+    time: consoleInstance.time.bind(consoleInstance),
+    timeEnd: consoleInstance.timeEnd.bind(consoleInstance),
+    timeLog: consoleInstance.timeLog.bind(consoleInstance),
+    trace: consoleInstance.trace.bind(consoleInstance),
+    table: consoleInstance.table.bind(consoleInstance),
+    group: consoleInstance.group.bind(consoleInstance),
+    groupCollapsed: consoleInstance.groupCollapsed.bind(consoleInstance),
+    groupEnd: consoleInstance.groupEnd.bind(consoleInstance),
+    clear: consoleInstance.clear.bind(consoleInstance),
+    profile: consoleInstance.profile.bind(consoleInstance),
+    profileEnd: consoleInstance.profileEnd.bind(consoleInstance),
+    timeStamp: consoleInstance.timeStamp.bind(consoleInstance)
+};
+module.exports = consoleModule;

package/dist/diagnostics_channel.d.ts

@@ -0,0 +1,36 @@
+/**
+ * diagnostics_channel。
+ *
+ * 它的语义是纯粹的「按名字的发布订阅」，本身不依赖任何平台能力，所以可以完整实现。
+ *
+ * 与 Node 的差异（都写进 BUILTINS.json）：
+ *   - Channel 的 bindStore / unbindStore / runStores 依赖 AsyncLocalStorage（需要 async_hooks），
+ *     Android 的 QuickJS 运行时没有物化这些钩子，所以这三个方法显式抛 ONJ_UNSUPPORTED，
+ *     而不是给一个"看着像但语义不对"的空实现；
+ *   - tracingChannel 未实现（依赖上面那组 API），同样显式拒绝。
+ */
+import { Subscriber, ChannelStore } from './lib/diagnostics-channel-types';
+declare class Channel {
+    constructor(name: string);
+    readonly name: string;
+    subscribers: Subscriber[];
+    get hasSubscribers(): boolean;
+    subscribe(onMessage: Subscriber): void;
+    unsubscribe(onMessage: Subscriber): void;
+    publish(message: unknown): void;
+    bindStore(_store: ChannelStore, _transform?: unknown): void;
+    unbindStore(_store: ChannelStore): void;
+    runStores(_context: unknown, _fn: Function, _thisArg?: unknown, ..._args: unknown[]): unknown;
+}
+declare function channel(name: string): Channel;
+declare function hasSubscribers(name: string): boolean;
+declare function subscribe(name: string, onMessage: Subscriber): void;
+declare function unsubscribe(name: string, onMessage: Subscriber): void;
+declare const diagnosticsChannel: {
+    channel: typeof channel;
+    hasSubscribers: typeof hasSubscribers;
+    subscribe: typeof subscribe;
+    unsubscribe: typeof unsubscribe;
+    Channel: typeof Channel;
+};
+export = diagnosticsChannel;

package/dist/diagnostics_channel.js

@@ -0,0 +1,76 @@
+'use strict';
+const channels = new Map();
+class Channel {
+    constructor(name) {
+        this.subscribers = [];
+        this.name = name;
+    }
+    get hasSubscribers() {
+        return this.subscribers.length > 0;
+    }
+    subscribe(onMessage) {
+        if (typeof onMessage !== 'function') {
+            throw new TypeError('The "onMessage" argument must be of type function.');
+        }
+        if (this.subscribers.indexOf(onMessage) < 0) {
+            this.subscribers.push(onMessage);
+        }
+    }
+    unsubscribe(onMessage) {
+        const index = this.subscribers.indexOf(onMessage);
+        if (index >= 0) {
+            this.subscribers.splice(index, 1);
+        }
+    }
+    publish(message) {
+        const listeners = this.subscribers.slice();
+        for (let index = 0; index < listeners.length; index += 1) {
+            listeners[index](message, this.name);
+        }
+    }
+    bindStore(_store, _transform) {
+        throw onjUnsupported('diagnostics_channel.Channel.bindStore');
+    }
+    unbindStore(_store) {
+        throw onjUnsupported('diagnostics_channel.Channel.unbindStore');
+    }
+    runStores(_context, _fn, _thisArg, ..._args) {
+        throw onjUnsupported('diagnostics_channel.Channel.runStores');
+    }
+}
+function onjUnsupported(feature) {
+    const failure = new Error(feature + ' 需要 AsyncLocalStorage（async_hooks），Android 的 QuickJS 运行时不提供异步钩子。');
+    failure.code = 'ONJ_UNSUPPORTED';
+    return failure;
+}
+function channel(name) {
+    if (typeof name !== 'string' && typeof name !== 'symbol') {
+        throw new TypeError('The "channel" argument must be of type string or symbol.');
+    }
+    const key = String(name);
+    const existing = channels.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = new Channel(key);
+    channels.set(key, created);
+    return created;
+}
+function hasSubscribers(name) {
+    const existing = channels.get(String(name));
+    return existing !== undefined && existing.hasSubscribers;
+}
+function subscribe(name, onMessage) {
+    channel(name).subscribe(onMessage);
+}
+function unsubscribe(name, onMessage) {
+    channel(name).unsubscribe(onMessage);
+}
+const diagnosticsChannel = {
+    channel: channel,
+    hasSubscribers: hasSubscribers,
+    subscribe: subscribe,
+    unsubscribe: unsubscribe,
+    Channel: Channel
+};
+module.exports = diagnosticsChannel;

package/dist/fs/promises.d.ts

@@ -3,7 +3,8 @@ declare class FileHandle {
     readonly fd: number;
     closed: boolean;
     constructor(fd: number);
-    private ensureOpen;
+    /** 公开而非 private：FileHandle 会随 fs/promises 一起被聚合导出，TS 不允许导出型别含私有成员（TS4094）。 */
+    ensureOpen(): void;
     /** Node 的 FileHandle.read 返回 { bytesRead, buffer }，不是裸数字。 */
     read(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): Promise<{
         bytesRead: number;

package/dist/fs/promises.js

@@ -40,6 +40,7 @@ class FileHandle {
         this.closed = false;
         this.fd = fd;
     }
+    /** 公开而非 private：FileHandle 会随 fs/promises 一起被聚合导出，TS 不允许导出型别含私有成员（TS4094）。 */
     ensureOpen() {
         if (this.closed) {
             const error = new Error('file descriptor was closed');