@yydb/yydb 0.0.15 → 0.0.17

package/dist/micro.js

@@ -1,160 +0,0 @@
-let nextHostId = 1;
-/**
- * Process-local registry for JS functions behind opaque host handles.
- * Rust keeps `host_id + function_id + version`, not the closure.
- */
-export class MicroSessionRegistry {
-    hostId;
-    nextFunctionId = 1;
-    byKey = new Map();
-    byFunctionId = new Map();
-    constructor(hostId = nextHostId++) {
-        this.hostId = hostId;
-    }
-    /** Installs a defined micro into the current session registry. */
-    register(definition) {
-        const key = logicalKey(definition.name, definition.version);
-        if (this.byKey.has(key)) {
-            throw new Error(`micro already registered: ${definition.name}@${definition.version}`);
-        }
-        const functionId = String(this.nextFunctionId++);
-        const handle = {
-            name: definition.name,
-            version: definition.version,
-            functionId,
-            hostId: this.hostId,
-            implementationVersion: 1,
-        };
-        const entry = { handle, definition: definition };
-        this.byKey.set(key, entry);
-        this.byFunctionId.set(functionId, entry);
-        return handle;
-    }
-    /** Returns a registered micro by opaque host handle. */
-    resolve(handle) {
-        if (handle.hostId !== this.hostId) {
-            return undefined;
-        }
-        return this.byFunctionId.get(handle.functionId)?.definition;
-    }
-    /** Invokes a registered micro from a wire `MicroHostInvoke` payload. */
-    invokeFromWire(payload) {
-        const handle = {
-            hostId: payload.hostId,
-            functionId: payload.functionId,
-            implementationVersion: payload.handleVersion,
-            name: '',
-            version: 0,
-        };
-        return this.invokeScalar(handle, [...payload.args]);
-    }
-    /** Invokes a registered scalar micro (host adapter entry point). */
-    invokeScalar(handle, args) {
-        const definition = this.resolve(handle);
-        if (!definition) {
-            throw new Error(`micro not found: ${handle.functionId}`);
-        }
-        if (definition.mode !== 'scalar') {
-            throw new Error(`micro ${definition.name} is not scalar mode`);
-        }
-        if (args.length !== definition.args.length) {
-            throw new Error(`micro ${definition.name} arity mismatch: expected ${definition.args.length}, got ${args.length}`);
-        }
-        validateArgTypes(definition, args);
-        const result = definition.fn(...args);
-        validateReturnType(definition.returns, result);
-        return result;
-    }
-    /** Lists logical names currently registered in this session. */
-    list() {
-        return [...this.byKey.values()].map((entry) => entry.definition.name).sort();
-    }
-}
-/** Builds a session-local micro definition without registering it. */
-export function defineMicro(input) {
-    if (!input.name.trim()) {
-        throw new Error('micro name must not be empty');
-    }
-    if (!Number.isInteger(input.version) || input.version <= 0) {
-        throw new Error('micro version must be a positive integer');
-    }
-    if (input.effect !== 'pure') {
-        throw new Error('TS micro effect must be pure in Phase 1');
-    }
-    if (!input.deterministic) {
-        throw new Error('TS micro must be deterministic in Phase 1');
-    }
-    if (typeof input.fn !== 'function') {
-        throw new Error('micro fn must be a function');
-    }
-    return {
-        name: input.name,
-        version: input.version,
-        args: input.args,
-        returns: input.returns,
-        effect: input.effect,
-        deterministic: input.deterministic,
-        mode: input.mode ?? 'scalar',
-        placement: 'host',
-        fn: input.fn,
-    };
-}
-function logicalKey(name, version) {
-    return `${name}@${version}`;
-}
-function validateArgTypes(definition, args) {
-    for (let index = 0; index < definition.args.length; index += 1) {
-        const kind = definition.args[index]?.kind;
-        const value = args[index];
-        switch (kind) {
-            case 'i64':
-                if (typeof value !== 'number' || !Number.isInteger(value)) {
-                    throw new Error(`micro ${definition.name} arg ${index} expects i64`);
-                }
-                break;
-            case 'bool':
-                if (typeof value !== 'boolean') {
-                    throw new Error(`micro ${definition.name} arg ${index} expects bool`);
-                }
-                break;
-            case 'text':
-                if (typeof value !== 'string') {
-                    throw new Error(`micro ${definition.name} arg ${index} expects text`);
-                }
-                break;
-            case 'null':
-                if (value !== null) {
-                    throw new Error(`micro ${definition.name} arg ${index} expects null`);
-                }
-                break;
-            default:
-                throw new Error(`unsupported micro arg kind: ${kind}`);
-        }
-    }
-}
-function validateReturnType(descriptor, value) {
-    switch (descriptor.kind) {
-        case 'i64':
-            if (typeof value !== 'number' || !Number.isInteger(value)) {
-                throw new Error('micro return expects i64');
-            }
-            break;
-        case 'bool':
-            if (typeof value !== 'boolean') {
-                throw new Error('micro return expects bool');
-            }
-            break;
-        case 'text':
-            if (typeof value !== 'string') {
-                throw new Error('micro return expects text');
-            }
-            break;
-        case 'null':
-            if (value !== null) {
-                throw new Error('micro return expects null');
-            }
-            break;
-        default:
-            throw new Error(`unsupported micro return kind: ${descriptor.kind}`);
-    }
-}

package/dist/native.d.ts

@@ -1,9 +0,0 @@
-export interface YydbNative {
-    version(): string;
-    serve(dbPath: string, bind: string, insecureBind?: boolean): void;
-    initDb(dbPath: string, schemaVersion: number, schemaDocument?: string | null): void;
-    infoText(dbPath: string): string;
-    readSchemaFile(schemaPath: string): string;
-}
-/** Load the platform native binding used by the `yydb` CLI. */
-export declare function loadNative(): YydbNative;

package/dist/native.js

@@ -1,32 +0,0 @@
-import { createRequire } from 'node:module';
-import fs from 'node:fs';
-import path from 'node:path';
-import { platformKey } from './resolve-bin.js';
-function loadModule(specifier) {
-    const require = createRequire(import.meta.url);
-    const loaded = require(specifier);
-    return (loaded.default ?? loaded);
-}
-/** Load the platform native binding used by the `yydb` CLI. */
-export function loadNative() {
-    const fromEnv = process.env.YYDB_NATIVE?.trim();
-    if (fromEnv) {
-        const bindingPath = path.resolve(fromEnv);
-        if (!fs.existsSync(bindingPath)) {
-            throw new Error(`YYDB_NATIVE points to missing binding: ${fromEnv}`);
-        }
-        return loadModule(bindingPath);
-    }
-    const key = platformKey();
-    if (!key) {
-        throw new Error(`YYDB native binding not available for ${process.platform}-${process.arch}`);
-    }
-    const pkg = `@yydb/yydb-${key}`;
-    try {
-        return loadModule(pkg);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`YYDB native binding not found. Reinstall @yydb/yydb with optional dependencies, set YYDB_NATIVE, or stage ${pkg}. ${message}`);
-    }
-}

package/dist/node/cli/cli.d.ts

@@ -1 +0,0 @@
-export declare function runCli(argv: string[]): Promise<number>;

package/dist/node/cli/cli.js

@@ -1,25 +0,0 @@
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createCli } from '@vmz/commander';
-import { registerInfoCommand } from './info-cmd.js';
-import { registerInitCommand } from './init-cmd.js';
-import { registerServeCommand } from './serve-cmd.js';
-import { registerVersionCommand } from './version-cmd.js';
-function buildYydbCli() {
-    const localesRoot = join(dirname(fileURLToPath(import.meta.url)), '../../../locales');
-    const cli = createCli('yydb').locales(localesRoot).intro('cli.intro');
-    registerVersionCommand(cli);
-    registerInitCommand(cli);
-    registerInfoCommand(cli);
-    registerServeCommand(cli);
-    return cli;
-}
-export async function runCli(argv) {
-    try {
-        return await buildYydbCli().parse(argv);
-    }
-    catch (error) {
-        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
-        return 1;
-    }
-}

package/dist/node/cli/info-cmd.d.ts

@@ -1,3 +0,0 @@
-import type { Cli, ParsedOptions } from '@vmz/commander';
-export declare function registerInfoCommand(cli: Cli): void;
-export declare function cmdInfo(options: ParsedOptions): number;

package/dist/node/cli/info-cmd.js

@@ -1,10 +0,0 @@
-import { loadNative } from '../native.js';
-import { requiredPositional } from './options.js';
-export function registerInfoCommand(cli) {
-    cli.command('info', 'cli.cmd.info').action((options) => cmdInfo(options));
-}
-export function cmdInfo(options) {
-    const dbPath = requiredPositional(options, 'info');
-    console.log(loadNative().infoText(dbPath));
-    return 0;
-}

package/dist/node/cli/init-cmd.d.ts

@@ -1,3 +0,0 @@
-import type { Cli, ParsedOptions } from '@vmz/commander';
-export declare function registerInitCommand(cli: Cli): void;
-export declare function cmdInit(options: ParsedOptions): number;

package/dist/node/cli/init-cmd.js

@@ -1,18 +0,0 @@
-import { loadNative } from '../native.js';
-import { requiredPositional, str } from './options.js';
-export function registerInitCommand(cli) {
-    cli.command('init', 'cli.cmd.init')
-        .option('--schema-version <n>', 'cli.opt.schema-version')
-        .option('--schema-file <path>', 'cli.opt.schema-file')
-        .action((options) => cmdInit(options));
-}
-export function cmdInit(options) {
-    const dbPath = requiredPositional(options, 'init');
-    const schemaVersion = Number.parseInt(str(options, 'schema-version') ?? '1', 10);
-    const schemaFile = str(options, 'schema-file');
-    const native = loadNative();
-    const schemaDocument = schemaFile ? native.readSchemaFile(schemaFile) : null;
-    native.initDb(dbPath, schemaVersion, schemaDocument);
-    console.log(`initialized ${dbPath}`);
-    return 0;
-}

package/dist/node/cli/options.d.ts

@@ -1,4 +0,0 @@
-import type { ParsedOptions } from '@vmz/commander';
-export declare function str(options: ParsedOptions, key: string): string | undefined;
-export declare function flag(options: ParsedOptions, key: string): boolean;
-export declare function requiredPositional(options: ParsedOptions, label: string): string;

package/dist/node/cli/options.js

@@ -1,14 +0,0 @@
-export function str(options, key) {
-    const value = options[key];
-    return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-export function flag(options, key) {
-    return options[key] === true;
-}
-export function requiredPositional(options, label) {
-    const value = options._[0];
-    if (!value) {
-        throw new Error(`${label} requires a path argument`);
-    }
-    return value;
-}

package/dist/node/cli/serve-cmd.d.ts

@@ -1,3 +0,0 @@
-import type { Cli, ParsedOptions } from '@vmz/commander';
-export declare function registerServeCommand(cli: Cli): void;
-export declare function cmdServe(options: ParsedOptions): number;

package/dist/node/cli/serve-cmd.js

@@ -1,14 +0,0 @@
-import { loadNative } from '../native.js';
-import { flag, requiredPositional, str } from './options.js';
-export function registerServeCommand(cli) {
-    cli.command('serve', 'cli.cmd.serve')
-        .option('--bind <host:port>', 'cli.opt.bind')
-        .option('--insecure-bind', 'cli.opt.insecure-bind')
-        .action((options) => cmdServe(options));
-}
-export function cmdServe(options) {
-    const dbPath = requiredPositional(options, 'serve');
-    const bind = str(options, 'bind') ?? '127.0.0.1:7700';
-    loadNative().serve(dbPath, bind, flag(options, 'insecure-bind'));
-    return 0;
-}

package/dist/node/cli/version-cmd.d.ts

@@ -1,3 +0,0 @@
-import type { Cli } from '@vmz/commander';
-export declare function registerVersionCommand(cli: Cli): void;
-export declare function cmdVersion(): number;

package/dist/node/cli/version-cmd.js

@@ -1,8 +0,0 @@
-import { loadNative } from '../native.js';
-export function registerVersionCommand(cli) {
-    cli.command('version', 'cli.cmd.version').action(() => cmdVersion());
-}
-export function cmdVersion() {
-    console.log(loadNative().version());
-    return 0;
-}

package/dist/node/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/node/cli.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-import { runCli } from './cli/cli.js';
-const code = await runCli(process.argv);
-if (code !== 0) {
-    process.exitCode = code;
-}

package/dist/node/database.d.ts

@@ -1,50 +0,0 @@
-import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
-import type { UdfScalarDescriptor } from '../shared/udf-types.js';
-export type { SchemaVersion } from '@yydb/yydb-client';
-export interface OpenOptions {
-    /** Override CLI script path (tests / special installs). */
-    cli?: string;
-    /** @deprecated Use `cli`. */
-    binary?: string;
-    /** Prefer a specific loopback port; default = ephemeral free port. */
-    port?: number;
-    /** Extra args after `serve <path> --bind …`. */
-    serveArgs?: string[];
-}
-/**
- * Node-facing YYDB handle. Looks like one library; owns a private loopback
- * `yydb serve` child under the hood.
- */
-export declare class Database {
-    readonly path: string;
-    readonly endpoint: string;
-    private client;
-    private child;
-    private readonly microRegistry;
-    private constructor();
-    /**
-     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
-     */
-    static open(dbPath: string, options?: OpenOptions): Promise<Database>;
-    serverVersion(): Promise<string>;
-    info(): Promise<string>;
-    getSchema(): Promise<import("@yydb/yydb-client").SchemaVersion | null>;
-    ensureSchema(version: number, document: string): Promise<void>;
-    get(key: string): Promise<Uint8Array | null>;
-    put(key: string, value: Uint8Array | string): Promise<void>;
-    /**
-     * Build a typed session-local micro definition. Does not register it with
-     * the engine until [`registerMicro`](./database.ts) is called.
-     */
-    defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: Parameters<typeof buildMicro<TArgs, TReturn>>[0]): DefinedMicro<TArgs, TReturn>;
-    /**
-     * Install a [`defineMicro`](./database.ts) definition into the current
-     * session registry and sync metadata to the private engine. Host micros are
-     * session-local and never written to `.yydb`.
-     */
-    registerMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
-    /** Invoke a registered scalar UDF on the private engine. */
-    callScalar(name: string, version: number, args: readonly (string | number | boolean | null)[]): Promise<string | number | boolean | null>;
-    /** Stop the private engine process. */
-    close(): Promise<void>;
-}

package/dist/node/database.js

@@ -1,173 +0,0 @@
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-import net from 'node:net';
-import path from 'node:path';
-import { connect } from '@yydb/yydb-client/node';
-import { defineMicro as buildMicro, microFingerprint, udfWireKind, MicroSessionRegistry } from '../shared/micro.js';
-import { resolveYydbCli } from './resolve-bin.js';
-async function freeLoopbackPort() {
-    return await new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, '127.0.0.1', () => {
-            const address = server.address();
-            if (!address || typeof address === 'string') {
-                server.close();
-                reject(new Error('could not allocate loopback port'));
-                return;
-            }
-            const { port } = address;
-            server.close((error) => {
-                if (error)
-                    reject(error);
-                else
-                    resolve(port);
-            });
-        });
-        server.on('error', reject);
-    });
-}
-async function waitForTcp(host, port, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        try {
-            await new Promise((resolve, reject) => {
-                const socket = net.connect({ host, port }, () => {
-                    socket.end();
-                    resolve();
-                });
-                socket.on('error', reject);
-            });
-            return;
-        }
-        catch {
-            await new Promise((r) => setTimeout(r, 40));
-        }
-    }
-    throw new Error(`yydb engine did not accept connections on ${host}:${port}`);
-}
-/**
- * Node-facing YYDB handle. Looks like one library; owns a private loopback
- * `yydb serve` child under the hood.
- */
-export class Database {
-    path;
-    endpoint;
-    client;
-    child;
-    microRegistry;
-    constructor(dbPath, endpoint, client, child) {
-        this.path = dbPath;
-        this.endpoint = endpoint;
-        this.client = client;
-        this.child = child;
-        this.microRegistry = new MicroSessionRegistry();
-        this.client.setMicroHostHandler((payload) => this.microRegistry.invokeFromWire(payload));
-    }
-    /**
-     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
-     */
-    static async open(dbPath, options = {}) {
-        const resolved = path.resolve(dbPath);
-        fs.mkdirSync(path.dirname(resolved), { recursive: true });
-        const cli = options.cli ?? options.binary ?? resolveYydbCli();
-        const port = options.port ?? (await freeLoopbackPort());
-        const bind = `127.0.0.1:${port}`;
-        const args = [cli, 'serve', resolved, '--bind', bind, ...(options.serveArgs ?? [])];
-        const child = spawn(process.execPath, args, {
-            stdio: 'pipe',
-            windowsHide: true,
-        });
-        let stderr = '';
-        child.stderr?.setEncoding('utf8');
-        child.stderr?.on('data', (chunk) => {
-            stderr += chunk;
-        });
-        const exitPromise = new Promise((_, reject) => {
-            child.once('exit', (code, signal) => {
-                reject(new Error(`yydb engine exited early (code=${code}, signal=${signal}): ${stderr.trim()}`));
-            });
-            child.once('error', reject);
-        });
-        try {
-            await Promise.race([waitForTcp('127.0.0.1', port, 8000), exitPromise]);
-            const client = await connect(bind);
-            child.removeAllListeners('exit');
-            child.removeAllListeners('error');
-            child.on('exit', () => {
-                /* closed via Database.close or crash */
-            });
-            return new Database(resolved, bind, client, child);
-        }
-        catch (error) {
-            child.kill('SIGTERM');
-            throw error;
-        }
-    }
-    async serverVersion() {
-        return this.client.serverVersion();
-    }
-    async info() {
-        return this.client.info();
-    }
-    async getSchema() {
-        return this.client.getSchema();
-    }
-    async ensureSchema(version, document) {
-        await this.client.ensureSchema(version, document);
-    }
-    async get(key) {
-        return this.client.get(key);
-    }
-    async put(key, value) {
-        await this.client.put(key, value);
-    }
-    /**
-     * Build a typed session-local micro definition. Does not register it with
-     * the engine until [`registerMicro`](./database.ts) is called.
-     */
-    defineMicro(definition) {
-        return buildMicro(definition);
-    }
-    /**
-     * Install a [`defineMicro`](./database.ts) definition into the current
-     * session registry and sync metadata to the private engine. Host micros are
-     * session-local and never written to `.yydb`.
-     */
-    async registerMicro(definition) {
-        const handle = this.microRegistry.register(definition);
-        await this.client.registerMicro({
-            hostId: handle.hostId,
-            handleVersion: handle.implementationVersion,
-            udfVersion: definition.version,
-            name: definition.name,
-            functionId: handle.functionId,
-            args: definition.args.map(udfWireKind),
-            returns: udfWireKind(definition.returns),
-            fingerprint: microFingerprint(definition.name, definition.version),
-        });
-        return handle;
-    }
-    /** Invoke a registered scalar UDF on the private engine. */
-    async callScalar(name, version, args) {
-        return this.client.callScalar(name, version, args);
-    }
-    /** Stop the private engine process. */
-    async close() {
-        this.client.close();
-        const child = this.child;
-        this.child = null;
-        if (!child || child.exitCode !== null || child.killed) {
-            return;
-        }
-        await new Promise((resolve) => {
-            child.once('exit', () => resolve());
-            child.kill('SIGTERM');
-            setTimeout(() => {
-                if (child.exitCode === null && !child.killed) {
-                    child.kill('SIGKILL');
-                }
-                resolve();
-            }, 2000);
-        });
-    }
-}

package/dist/node/index.d.ts

@@ -1,7 +0,0 @@
-export { Database, type OpenOptions } from './database.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
-export type { YydbErrorCode, YydbErrorOptions } from '@yydb/yydb-client';
-export { defineMicro, type DefinedMicro, type MicroHandle, type TsMicroDefinitionInput, MicroSessionRegistry } from '../shared/micro.js';
-export { type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarDescriptor, type UdfScalarKind, } from '../shared/udf-types.js';
-export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';
-export * from '../shared/vos.js';

package/dist/node/index.js

@@ -1,5 +0,0 @@
-export { Database } from './database.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
-export { defineMicro, MicroSessionRegistry } from '../shared/micro.js';
-export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';
-export * from '../shared/vos.js';

package/dist/node/native.d.ts

@@ -1,9 +0,0 @@
-export interface YydbNative {
-    version(): string;
-    serve(dbPath: string, bind: string, insecureBind?: boolean): void;
-    initDb(dbPath: string, schemaVersion: number, schemaDocument?: string | null): void;
-    infoText(dbPath: string): string;
-    readSchemaFile(schemaPath: string): string;
-}
-/** Load the platform native binding used by the `yydb` CLI. */
-export declare function loadNative(): YydbNative;

package/dist/node/native.js

@@ -1,32 +0,0 @@
-import { createRequire } from 'node:module';
-import fs from 'node:fs';
-import path from 'node:path';
-import { platformKey } from './resolve-bin.js';
-function loadModule(specifier) {
-    const require = createRequire(import.meta.url);
-    const loaded = require(specifier);
-    return (loaded.default ?? loaded);
-}
-/** Load the platform native binding used by the `yydb` CLI. */
-export function loadNative() {
-    const fromEnv = process.env.YYDB_NATIVE?.trim();
-    if (fromEnv) {
-        const bindingPath = path.resolve(fromEnv);
-        if (!fs.existsSync(bindingPath)) {
-            throw new Error(`YYDB_NATIVE points to missing binding: ${fromEnv}`);
-        }
-        return loadModule(bindingPath);
-    }
-    const key = platformKey();
-    if (!key) {
-        throw new Error(`YYDB native binding not available for ${process.platform}-${process.arch}`);
-    }
-    const pkg = `@yydb/yydb-${key}`;
-    try {
-        return loadModule(pkg);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`YYDB native binding not found. Reinstall @yydb/yydb with optional dependencies, set YYDB_NATIVE, or stage ${pkg}. ${message}`);
-    }
-}

package/dist/node/resolve-bin.d.ts

@@ -1,15 +0,0 @@
-/// <reference types="node" />
-export type PlatformKey = 'win32-x64' | 'linux-x64' | 'darwin-x64' | 'darwin-arm64';
-/** Map Node platform/arch to optionalDependency package suffix. */
-export declare function platformKey(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PlatformKey | null;
-/** Native binding filename inside each `@yydb/yydb-<platform>` package `lib/`. */
-export declare function nativeBindingName(key: PlatformKey): string;
-/**
- * Resolve the TypeScript `yydb` CLI entry script.
- * Order: `YYDB_CLI` → this package `dist/cli.js`.
- */
-export declare function resolveYydbCli(): string;
-/**
- * @deprecated Use {@link resolveYydbCli}. Kept for callers that still import this name.
- */
-export declare function resolveYydbBinary(): string;