@robinpath/cli 1.73.0

package/modules/stream.js

@@ -0,0 +1,322 @@
+/**
+ * Native stream module for RobinPath.
+ * Readable, Writable, Transform, Duplex, PassThrough, and pipeline.
+ */
+import { Readable, Writable, Transform, Duplex, PassThrough, pipeline as _pipeline } from 'node:stream';
+import { toStr, toNum, requireArgs } from './_helpers.js';
+
+const _streams = new Map();
+let _nextId = 1;
+
+export const StreamFunctions = {
+
+    readable: (args) => {
+        const data = args[0];
+        const id = `readable_${_nextId++}`;
+        let chunks;
+        if (typeof data === 'string') {
+            chunks = [data];
+        } else if (Array.isArray(data)) {
+            chunks = data.map(c => toStr(c));
+        } else {
+            chunks = [toStr(data)];
+        }
+        const stream = new Readable({
+            read() {
+                if (chunks.length > 0) this.push(chunks.shift());
+                else this.push(null);
+            }
+        });
+        _streams.set(id, { stream, data: '' });
+        stream.on('data', (chunk) => {
+            const entry = _streams.get(id);
+            if (entry) entry.data += chunk.toString();
+        });
+        return id;
+    },
+
+    writable: (args) => {
+        const id = `writable_${_nextId++}`;
+        let collected = '';
+        const stream = new Writable({
+            write(chunk, encoding, callback) {
+                collected += chunk.toString();
+                const entry = _streams.get(id);
+                if (entry) entry.data = collected;
+                callback();
+            }
+        });
+        _streams.set(id, { stream, data: '' });
+        return id;
+    },
+
+    transform: (args) => {
+        const id = `transform_${_nextId++}`;
+        const stream = new Transform({
+            transform(chunk, encoding, callback) {
+                callback(null, chunk);
+            }
+        });
+        _streams.set(id, { stream, data: '' });
+        stream.on('data', (chunk) => {
+            const entry = _streams.get(id);
+            if (entry) entry.data += chunk.toString();
+        });
+        return id;
+    },
+
+    duplex: (args) => {
+        const id = `duplex_${_nextId++}`;
+        const stream = new Duplex({
+            read() {},
+            write(chunk, encoding, callback) {
+                this.push(chunk);
+                callback();
+            }
+        });
+        _streams.set(id, { stream, data: '' });
+        stream.on('data', (chunk) => {
+            const entry = _streams.get(id);
+            if (entry) entry.data += chunk.toString();
+        });
+        return id;
+    },
+
+    passThrough: (args) => {
+        const id = `passthrough_${_nextId++}`;
+        const stream = new PassThrough();
+        _streams.set(id, { stream, data: '' });
+        stream.on('data', (chunk) => {
+            const entry = _streams.get(id);
+            if (entry) entry.data += chunk.toString();
+        });
+        return id;
+    },
+
+    write: (args) => {
+        requireArgs('stream.write', args, 2);
+        const id = toStr(args[0]);
+        const data = toStr(args[1]);
+        const entry = _streams.get(id);
+        if (!entry) throw new Error(`stream.write: stream ${id} not found`);
+        return new Promise((resolve, reject) => {
+            entry.stream.write(data, (err) => {
+                if (err) reject(err);
+                else resolve(true);
+            });
+        });
+    },
+
+    read: (args) => {
+        requireArgs('stream.read', args, 1);
+        const id = toStr(args[0]);
+        const entry = _streams.get(id);
+        if (!entry) throw new Error(`stream.read: stream ${id} not found`);
+        const data = entry.data;
+        entry.data = '';
+        return data;
+    },
+
+    end: (args) => {
+        requireArgs('stream.end', args, 1);
+        const id = toStr(args[0]);
+        const entry = _streams.get(id);
+        if (!entry) throw new Error(`stream.end: stream ${id} not found`);
+        entry.stream.end();
+        return true;
+    },
+
+    destroy: (args) => {
+        requireArgs('stream.destroy', args, 1);
+        const id = toStr(args[0]);
+        const entry = _streams.get(id);
+        if (entry) {
+            entry.stream.destroy();
+            _streams.delete(id);
+            return true;
+        }
+        return false;
+    },
+
+    pipe: (args) => {
+        requireArgs('stream.pipe', args, 2);
+        const srcId = toStr(args[0]);
+        const destId = toStr(args[1]);
+        const src = _streams.get(srcId);
+        const dest = _streams.get(destId);
+        if (!src) throw new Error(`stream.pipe: source ${srcId} not found`);
+        if (!dest) throw new Error(`stream.pipe: destination ${destId} not found`);
+        src.stream.pipe(dest.stream);
+        return destId;
+    },
+
+    pipeline: (args) => {
+        if (!Array.isArray(args[0]) && args.length < 2) {
+            throw new Error('stream.pipeline requires at least 2 stream IDs');
+        }
+        const ids = Array.isArray(args[0]) ? args[0] : args;
+        const streams = ids.map(id => {
+            const entry = _streams.get(toStr(id));
+            if (!entry) throw new Error(`stream.pipeline: stream ${id} not found`);
+            return entry.stream;
+        });
+        return new Promise((resolve, reject) => {
+            _pipeline(...streams, (err) => {
+                if (err) reject(err);
+                else resolve(true);
+            });
+        });
+    },
+
+    toBuffer: (args) => {
+        requireArgs('stream.toBuffer', args, 1);
+        const id = toStr(args[0]);
+        const entry = _streams.get(id);
+        if (!entry) throw new Error(`stream.toBuffer: stream ${id} not found`);
+        return new Promise((resolve) => {
+            const chunks = [];
+            entry.stream.on('data', (chunk) => chunks.push(chunk));
+            entry.stream.on('end', () => {
+                resolve(Buffer.concat(chunks).toString('base64'));
+            });
+            // If already ended
+            if (entry.stream.readableEnded) {
+                resolve(Buffer.from(entry.data).toString('base64'));
+            }
+        });
+    },
+
+    toString: (args) => {
+        requireArgs('stream.toString', args, 1);
+        const id = toStr(args[0]);
+        const entry = _streams.get(id);
+        if (!entry) throw new Error(`stream.toString: stream ${id} not found`);
+        return new Promise((resolve) => {
+            let data = '';
+            entry.stream.on('data', (chunk) => { data += chunk.toString(); });
+            entry.stream.on('end', () => resolve(data));
+            if (entry.stream.readableEnded) resolve(entry.data);
+        });
+    },
+
+    fromString: (args) => {
+        requireArgs('stream.fromString', args, 1);
+        const data = toStr(args[0]);
+        const id = `readable_${_nextId++}`;
+        const stream = Readable.from([data]);
+        _streams.set(id, { stream, data });
+        return id;
+    },
+
+    fromArray: (args) => {
+        requireArgs('stream.fromArray', args, 1);
+        const arr = Array.isArray(args[0]) ? args[0] : [args[0]];
+        const id = `readable_${_nextId++}`;
+        const stream = Readable.from(arr.map(a => toStr(a)));
+        _streams.set(id, { stream, data: arr.join('') });
+        return id;
+    },
+
+    active: () => Array.from(_streams.keys()),
+
+    count: () => _streams.size
+};
+
+export const StreamFunctionMetadata = {
+    readable: {
+        description: 'Create a readable stream from data',
+        parameters: [{ name: 'data', dataType: 'any', description: 'String or array of chunks', formInputType: 'textarea', required: true }],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.readable "hello world"'
+    },
+    writable: {
+        description: 'Create a writable stream that collects data',
+        parameters: [],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.writable'
+    },
+    transform: {
+        description: 'Create a transform (pass-through) stream',
+        parameters: [],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.transform'
+    },
+    duplex: {
+        description: 'Create a duplex (read/write) stream',
+        parameters: [],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.duplex'
+    },
+    passThrough: {
+        description: 'Create a passthrough stream',
+        parameters: [],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.passThrough'
+    },
+    write: {
+        description: 'Write data to a stream',
+        parameters: [
+            { name: 'streamId', dataType: 'string', description: 'Stream handle ID', formInputType: 'text', required: true },
+            { name: 'data', dataType: 'string', description: 'Data to write', formInputType: 'textarea', required: true }
+        ],
+        returnType: 'boolean', returnDescription: 'true on success', example: 'stream.write $s "data"'
+    },
+    read: {
+        description: 'Read buffered data from a stream',
+        parameters: [{ name: 'streamId', dataType: 'string', description: 'Stream handle ID', formInputType: 'text', required: true }],
+        returnType: 'string', returnDescription: 'Buffered data', example: 'stream.read $s'
+    },
+    end: {
+        description: 'Signal end of stream',
+        parameters: [{ name: 'streamId', dataType: 'string', description: 'Stream handle ID', formInputType: 'text', required: true }],
+        returnType: 'boolean', returnDescription: 'true', example: 'stream.end $s'
+    },
+    destroy: {
+        description: 'Destroy a stream and free resources',
+        parameters: [{ name: 'streamId', dataType: 'string', description: 'Stream handle ID', formInputType: 'text', required: true }],
+        returnType: 'boolean', returnDescription: 'true if destroyed', example: 'stream.destroy $s'
+    },
+    pipe: {
+        description: 'Pipe one stream into another',
+        parameters: [
+            { name: 'sourceId', dataType: 'string', description: 'Source stream', formInputType: 'text', required: true },
+            { name: 'destId', dataType: 'string', description: 'Destination stream', formInputType: 'text', required: true }
+        ],
+        returnType: 'string', returnDescription: 'Destination stream ID', example: 'stream.pipe $src $dest'
+    },
+    pipeline: {
+        description: 'Chain multiple streams together with error propagation',
+        parameters: [{ name: 'streamIds', dataType: 'array', description: 'Array of stream IDs to chain', formInputType: 'json', required: true }],
+        returnType: 'boolean', returnDescription: 'true on completion', example: 'stream.pipeline [$s1, $s2, $s3]'
+    },
+    toBuffer: {
+        description: 'Collect stream data as base64 buffer',
+        parameters: [{ name: 'streamId', dataType: 'string', description: 'Stream handle ID', formInputType: 'text', required: true }],
+        returnType: 'string', returnDescription: 'Base64-encoded buffer', example: 'stream.toBuffer $s'
+    },
+    toString: {
+        description: 'Collect stream data as string',
+        parameters: [{ name: 'streamId', dataType: 'string', description: 'Stream handle ID', formInputType: 'text', required: true }],
+        returnType: 'string', returnDescription: 'Collected string', example: 'stream.toString $s'
+    },
+    fromString: {
+        description: 'Create a readable stream from a string',
+        parameters: [{ name: 'data', dataType: 'string', description: 'Input string', formInputType: 'textarea', required: true }],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.fromString "hello"'
+    },
+    fromArray: {
+        description: 'Create a readable stream from an array',
+        parameters: [{ name: 'data', dataType: 'array', description: 'Array of chunks', formInputType: 'json', required: true }],
+        returnType: 'string', returnDescription: 'Stream handle ID', example: 'stream.fromArray ["chunk1", "chunk2"]'
+    },
+    active: { description: 'List all active stream handles', parameters: [], returnType: 'array', returnDescription: 'Array of stream IDs', example: 'stream.active' },
+    count: { description: 'Count active streams', parameters: [], returnType: 'number', returnDescription: 'Number of active streams', example: 'stream.count' }
+};
+
+export const StreamModuleMetadata = {
+    description: 'Stream operations: Readable, Writable, Transform, Duplex, PassThrough, pipe, pipeline',
+    methods: Object.keys(StreamFunctions)
+};
+
+export default {
+    name: 'stream',
+    functions: StreamFunctions,
+    functionMetadata: StreamFunctionMetadata,
+    moduleMetadata: StreamModuleMetadata,
+    global: false
+};

package/modules/string_decoder.js

@@ -0,0 +1,106 @@
+/**
+ * Native string_decoder module for RobinPath.
+ * Decode Buffer sequences to strings, handling multi-byte characters.
+ */
+import { StringDecoder } from 'node:string_decoder';
+import { toStr, requireArgs } from './_helpers.js';
+
+const _decoders = new Map();
+let _nextId = 1;
+
+export const StringDecoderFunctions = {
+
+    create: (args) => {
+        const encoding = toStr(args[0], 'utf-8');
+        const id = `decoder_${_nextId++}`;
+        _decoders.set(id, new StringDecoder(encoding));
+        return id;
+    },
+
+    write: (args) => {
+        requireArgs('stringDecoder.write', args, 2);
+        const id = toStr(args[0]);
+        const decoder = _decoders.get(id);
+        if (!decoder) throw new Error(`stringDecoder.write: decoder ${id} not found`);
+        const buf = Buffer.from(toStr(args[1]), 'base64');
+        return decoder.write(buf);
+    },
+
+    end: (args) => {
+        requireArgs('stringDecoder.end', args, 1);
+        const id = toStr(args[0]);
+        const decoder = _decoders.get(id);
+        if (!decoder) throw new Error(`stringDecoder.end: decoder ${id} not found`);
+        const result = decoder.end();
+        _decoders.delete(id);
+        return result;
+    },
+
+    decode: (args) => {
+        requireArgs('stringDecoder.decode', args, 1);
+        const encoding = toStr(args[1], 'utf-8');
+        const buf = Buffer.from(toStr(args[0]), 'base64');
+        const decoder = new StringDecoder(encoding);
+        return decoder.write(buf) + decoder.end();
+    },
+
+    destroy: (args) => {
+        requireArgs('stringDecoder.destroy', args, 1);
+        const id = toStr(args[0]);
+        if (_decoders.has(id)) {
+            _decoders.delete(id);
+            return true;
+        }
+        return false;
+    },
+
+    active: () => Array.from(_decoders.keys())
+};
+
+export const StringDecoderFunctionMetadata = {
+    create: {
+        description: 'Create a string decoder for an encoding',
+        parameters: [{ name: 'encoding', dataType: 'string', description: 'Encoding (utf-8, ascii, base64, hex, etc.)', formInputType: 'text', required: false, defaultValue: 'utf-8' }],
+        returnType: 'string', returnDescription: 'Decoder handle ID', example: 'stringDecoder.create "utf-8"'
+    },
+    write: {
+        description: 'Write buffer data through decoder',
+        parameters: [
+            { name: 'decoderId', dataType: 'string', description: 'Decoder handle', formInputType: 'text', required: true },
+            { name: 'buffer', dataType: 'string', description: 'Base64-encoded buffer data', formInputType: 'text', required: true }
+        ],
+        returnType: 'string', returnDescription: 'Decoded string', example: 'stringDecoder.write $dec $buf'
+    },
+    end: {
+        description: 'Flush remaining bytes and close decoder',
+        parameters: [{ name: 'decoderId', dataType: 'string', description: 'Decoder handle', formInputType: 'text', required: true }],
+        returnType: 'string', returnDescription: 'Any remaining decoded bytes', example: 'stringDecoder.end $dec'
+    },
+    decode: {
+        description: 'One-shot decode: buffer to string',
+        parameters: [
+            { name: 'buffer', dataType: 'string', description: 'Base64-encoded buffer', formInputType: 'text', required: true },
+            { name: 'encoding', dataType: 'string', description: 'Encoding (default: utf-8)', formInputType: 'text', required: false, defaultValue: 'utf-8' }
+        ],
+        returnType: 'string', returnDescription: 'Decoded string', example: 'stringDecoder.decode $buf "utf-8"'
+    },
+    destroy: {
+        description: 'Destroy a decoder',
+        parameters: [{ name: 'decoderId', dataType: 'string', description: 'Decoder handle', formInputType: 'text', required: true }],
+        returnType: 'boolean', returnDescription: 'true if destroyed', example: 'stringDecoder.destroy $dec'
+    },
+    active: { description: 'List active decoders', parameters: [], returnType: 'array', returnDescription: 'Array of decoder IDs', example: 'stringDecoder.active' }
+};
+
+export const StringDecoderModuleMetadata = {
+    description: 'String decoder: convert Buffer sequences to strings with multi-byte character handling',
+    methods: Object.keys(StringDecoderFunctions)
+};
+
+export default {
+    name: 'stringDecoder',
+    functions: StringDecoderFunctions,
+    functionMetadata: StringDecoderFunctionMetadata,
+    moduleMetadata: StringDecoderModuleMetadata,
+    global: false
+};

package/modules/timer.js

@@ -0,0 +1,167 @@
+/**
+ * Native timer module for RobinPath.
+ * Sleep, delay, and interval utilities.
+ */
+import { toNum, requireArgs } from './_helpers.js';
+
+const _intervals = new Map();
+const _timeouts = new Map();
+let _nextId = 1;
+
+export const TimerFunctions = {
+
+    sleep: (args) => {
+        const ms = toNum(args[0], 1000);
+        return new Promise(resolve => setTimeout(() => resolve(true), ms));
+    },
+
+    delay: (args) => {
+        const ms = toNum(args[0], 1000);
+        return new Promise(resolve => setTimeout(() => resolve(true), ms));
+    },
+
+    setTimeout: (args, callback) => {
+        requireArgs('timer.setTimeout', args, 1);
+        const ms = toNum(args[0], 1000);
+        const id = `timeout_${_nextId++}`;
+        const handle = setTimeout(() => {
+            _timeouts.delete(id);
+            if (callback) callback([id]);
+        }, ms);
+        _timeouts.set(id, handle);
+        return id;
+    },
+
+    setInterval: (args, callback) => {
+        requireArgs('timer.setInterval', args, 1);
+        const ms = toNum(args[0], 1000);
+        const id = `interval_${_nextId++}`;
+        const handle = setInterval(() => {
+            if (callback) callback([id]);
+        }, ms);
+        _intervals.set(id, handle);
+        return id;
+    },
+
+    clearTimeout: (args) => {
+        requireArgs('timer.clearTimeout', args, 1);
+        const id = String(args[0]);
+        const handle = _timeouts.get(id);
+        if (handle) {
+            clearTimeout(handle);
+            _timeouts.delete(id);
+            return true;
+        }
+        return false;
+    },
+
+    clearInterval: (args) => {
+        requireArgs('timer.clearInterval', args, 1);
+        const id = String(args[0]);
+        const handle = _intervals.get(id);
+        if (handle) {
+            clearInterval(handle);
+            _intervals.delete(id);
+            return true;
+        }
+        return false;
+    },
+
+    clearAll: () => {
+        for (const handle of _timeouts.values()) clearTimeout(handle);
+        for (const handle of _intervals.values()) clearInterval(handle);
+        _timeouts.clear();
+        _intervals.clear();
+        return true;
+    },
+
+    active: () => {
+        return {
+            timeouts: Array.from(_timeouts.keys()),
+            intervals: Array.from(_intervals.keys())
+        };
+    },
+
+    measure: async (args, callback) => {
+        const start = process.hrtime.bigint();
+        if (callback) await callback([]);
+        const end = process.hrtime.bigint();
+        const ms = Number(end - start) / 1_000_000;
+        return ms;
+    },
+
+    timestamp: () => Date.now(),
+
+    now: () => performance.now()
+};
+
+export const TimerFunctionMetadata = {
+    sleep: {
+        description: 'Pause execution for a duration',
+        parameters: [{ name: 'milliseconds', dataType: 'number', description: 'Duration in ms (default: 1000)', formInputType: 'number', required: false, defaultValue: 1000 }],
+        returnType: 'boolean', returnDescription: 'true when done', example: 'timer.sleep 2000'
+    },
+    delay: {
+        description: 'Alias for sleep',
+        parameters: [{ name: 'milliseconds', dataType: 'number', description: 'Duration in ms', formInputType: 'number', required: false, defaultValue: 1000 }],
+        returnType: 'boolean', returnDescription: 'true when done', example: 'timer.delay 500'
+    },
+    setTimeout: {
+        description: 'Execute callback after a delay',
+        parameters: [{ name: 'milliseconds', dataType: 'number', description: 'Delay in ms', formInputType: 'number', required: true }],
+        returnType: 'string', returnDescription: 'Timeout handle ID', example: 'timer.setTimeout 1000'
+    },
+    setInterval: {
+        description: 'Execute callback repeatedly at an interval',
+        parameters: [{ name: 'milliseconds', dataType: 'number', description: 'Interval in ms', formInputType: 'number', required: true }],
+        returnType: 'string', returnDescription: 'Interval handle ID', example: 'timer.setInterval 5000'
+    },
+    clearTimeout: {
+        description: 'Cancel a pending timeout',
+        parameters: [{ name: 'id', dataType: 'string', description: 'Timeout handle ID', formInputType: 'text', required: true }],
+        returnType: 'boolean', returnDescription: 'true if cleared', example: 'timer.clearTimeout $id'
+    },
+    clearInterval: {
+        description: 'Cancel a repeating interval',
+        parameters: [{ name: 'id', dataType: 'string', description: 'Interval handle ID', formInputType: 'text', required: true }],
+        returnType: 'boolean', returnDescription: 'true if cleared', example: 'timer.clearInterval $id'
+    },
+    clearAll: {
+        description: 'Cancel all active timeouts and intervals',
+        parameters: [],
+        returnType: 'boolean', returnDescription: 'true', example: 'timer.clearAll'
+    },
+    active: {
+        description: 'List all active timers',
+        parameters: [],
+        returnType: 'object', returnDescription: 'Object with timeouts and intervals arrays', example: 'timer.active'
+    },
+    measure: {
+        description: 'Measure execution time of a callback in milliseconds',
+        parameters: [],
+        returnType: 'number', returnDescription: 'Execution time in ms', example: 'timer.measure'
+    },
+    timestamp: {
+        description: 'Get current Unix timestamp in milliseconds',
+        parameters: [],
+        returnType: 'number', returnDescription: 'Unix timestamp (ms)', example: 'timer.timestamp'
+    },
+    now: {
+        description: 'Get high-resolution monotonic time (performance.now)',
+        parameters: [],
+        returnType: 'number', returnDescription: 'Time in ms', example: 'timer.now'
+    }
+};
+
+export const TimerModuleMetadata = {
+    description: 'Timer operations: sleep, delay, setTimeout, setInterval, measure, and timestamp',
+    methods: Object.keys(TimerFunctions)
+};
+
+export default {
+    name: 'timer',
+    functions: TimerFunctions,
+    functionMetadata: TimerFunctionMetadata,
+    moduleMetadata: TimerModuleMetadata,
+    global: false
+};