@yydb/yydb 0.0.1 → 0.0.2

package/dist/generator/parse-vos.js

@@ -0,0 +1,149 @@
+export class VosParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VosParseError';
+    }
+}
+/** Interim VOS subset parser for `yydb generate` (MVP). */
+export function parseVosSubset(source, schemaVersion) {
+    if (source.includes('\0')) {
+        throw new VosParseError('VOS document must not contain NUL bytes');
+    }
+    let normalized = source.startsWith('\uFEFF') ? source.slice(1) : source;
+    normalized = normalized.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const lexer = new Lexer(normalized);
+    const tables = [];
+    while (!lexer.eof()) {
+        lexer.skipWsAndComments();
+        if (lexer.eof()) {
+            break;
+        }
+        tables.push(parseTable(lexer));
+    }
+    if (tables.length === 0) {
+        throw new VosParseError('expected at least one `table` declaration');
+    }
+    return {
+        vosSource: normalized,
+        schemaVersion,
+        tables,
+    };
+}
+function parseTable(lexer) {
+    lexer.expectIdent('table');
+    const name = lexer.expectAnyIdent();
+    lexer.expectPunct('{');
+    const fields = [];
+    while (true) {
+        lexer.skipWsAndComments();
+        if (lexer.eatPunct('}')) {
+            break;
+        }
+        if (lexer.eatPunct('@')) {
+            lexer.expectPunct('@');
+            const attr = lexer.expectAnyIdent();
+            if (attr !== 'id') {
+                throw new VosParseError(`unsupported table attribute \`@@${attr}\` (MVP supports \`@@id\` only)`);
+            }
+            lexer.expectPunct(':');
+            const ty = parseScalar(lexer);
+            fields.push({ name: 'id', ty, isId: true });
+        }
+        else {
+            const fieldName = lexer.expectAnyIdent();
+            lexer.expectPunct(':');
+            const ty = parseScalar(lexer);
+            fields.push({ name: fieldName, ty, isId: false });
+        }
+        lexer.skipWsAndComments();
+        lexer.eatPunct(',');
+    }
+    if (!fields.some((field) => field.isId)) {
+        throw new VosParseError(`table \`${name}\` requires \`@@id: <type>\``);
+    }
+    return { name, fields };
+}
+function parseScalar(lexer) {
+    const name = lexer.expectAnyIdent();
+    switch (name) {
+        case 'uuid':
+            return 'uuid';
+        case 'utf8':
+            return 'utf8';
+        case 'bool':
+            return 'bool';
+        case 'i64':
+            return 'i64';
+        case 'f64':
+            return 'f64';
+        default:
+            throw new VosParseError(`unsupported scalar type \`${name}\` (MVP: uuid, utf8, bool, i64, f64)`);
+    }
+}
+class Lexer {
+    src;
+    i = 0;
+    constructor(src) {
+        this.src = src;
+    }
+    eof() {
+        return this.i >= this.src.length;
+    }
+    peek() {
+        return this.src[this.i];
+    }
+    bump() {
+        const ch = this.peek();
+        if (ch === undefined) {
+            return undefined;
+        }
+        this.i += 1;
+        return ch;
+    }
+    skipWsAndComments() {
+        while (true) {
+            while (this.peek() !== undefined && /\s/.test(this.peek())) {
+                this.bump();
+            }
+            if (this.src.startsWith('//', this.i)) {
+                while (this.peek() !== undefined && this.peek() !== '\n') {
+                    this.bump();
+                }
+                continue;
+            }
+            break;
+        }
+    }
+    eatPunct(expected) {
+        this.skipWsAndComments();
+        if (this.peek() === expected) {
+            this.bump();
+            return true;
+        }
+        return false;
+    }
+    expectPunct(expected) {
+        if (!this.eatPunct(expected)) {
+            throw new VosParseError(`expected \`${expected}\` at byte ${this.i}`);
+        }
+    }
+    expectIdent(expected) {
+        const got = this.expectAnyIdent();
+        if (got !== expected) {
+            throw new VosParseError(`expected \`${expected}\`, found \`${got}\``);
+        }
+    }
+    expectAnyIdent() {
+        this.skipWsAndComments();
+        const start = this.i;
+        const first = this.peek();
+        if (first === undefined || !/[A-Za-z_]/.test(first)) {
+            throw new VosParseError(`expected identifier at byte ${this.i}`);
+        }
+        this.bump();
+        while (this.peek() !== undefined && /[A-Za-z0-9_]/.test(this.peek())) {
+            this.bump();
+        }
+        return this.src.slice(start, this.i);
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export { Database, type OpenOptions } from "./database.js";
-export { resolveYydbBinary, platformKey } from "./resolve-bin.js";
+export { Database, type OpenOptions } from './database.js';
+export { defineMicro, type DefinedMicro, type MicroHandle, type TsMicroDefinitionInput, MicroSessionRegistry } from './micro.js';
+export { bool, i64, nullType, text, type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarKind, type UdfTypeDescriptor, } from './udf-types.js';
+export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';

package/dist/index.js

@@ -1,2 +1,4 @@
-export { Database } from "./database.js";
-export { resolveYydbBinary, platformKey } from "./resolve-bin.js";
+export { Database } from './database.js';
+export { defineMicro, MicroSessionRegistry } from './micro.js';
+export { bool, i64, nullType, text, } from './udf-types.js';
+export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';

package/dist/micro.d.ts

@@ -0,0 +1,63 @@
+import type { InferUdfArgs, InferUdfReturn, MicroEffect, MicroInvocationMode, UdfTypeDescriptor } from './udf-types.js';
+/** Input accepted by [`Database.defineMicro`](./database.ts). */
+export interface TsMicroDefinitionInput<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor> {
+    readonly name: string;
+    readonly version: number;
+    readonly args: TArgs;
+    readonly returns: TReturn;
+    readonly effect: MicroEffect;
+    readonly deterministic: boolean;
+    readonly mode?: MicroInvocationMode;
+    readonly fn: (...args: InferUdfArgs<TArgs>) => InferUdfReturn<TReturn>;
+}
+/** Opaque definition produced by `defineMicro` before session registration. */
+export interface DefinedMicro<TArgs extends readonly UdfTypeDescriptor[] = readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor = UdfTypeDescriptor> {
+    readonly name: string;
+    readonly version: number;
+    readonly args: TArgs;
+    readonly returns: TReturn;
+    readonly effect: MicroEffect;
+    readonly deterministic: boolean;
+    readonly mode: MicroInvocationMode;
+    readonly placement: 'host';
+    readonly fn: (...args: InferUdfArgs<TArgs>) => InferUdfReturn<TReturn>;
+}
+/** Handle returned after `registerMicro` installs a micro into the session. */
+export interface MicroHandle {
+    readonly name: string;
+    readonly version: number;
+    readonly functionId: string;
+    readonly hostId: number;
+    /** Monotonic host implementation version for opaque handle checks. */
+    readonly implementationVersion: number;
+}
+type AnyDefinedMicro = DefinedMicro<readonly UdfTypeDescriptor[], UdfTypeDescriptor>;
+/**
+ * Process-local registry for JS functions behind opaque host handles.
+ * Rust keeps `host_id + function_id + version`, not the closure.
+ */
+export declare class MicroSessionRegistry {
+    readonly hostId: number;
+    private nextFunctionId;
+    private readonly byKey;
+    private readonly byFunctionId;
+    constructor(hostId?: number);
+    /** Installs a defined micro into the current session registry. */
+    register<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(definition: DefinedMicro<TArgs, TReturn>): MicroHandle;
+    /** Returns a registered micro by opaque host handle. */
+    resolve(handle: MicroHandle): AnyDefinedMicro | undefined;
+    /** Invokes a registered micro from a wire `MicroHostInvoke` payload. */
+    invokeFromWire(payload: {
+        hostId: number;
+        handleVersion: number;
+        functionId: string;
+        args: readonly unknown[];
+    }): string | number | boolean | null;
+    /** Invokes a registered scalar micro (host adapter entry point). */
+    invokeScalar(handle: MicroHandle, args: unknown[]): unknown;
+    /** Lists logical names currently registered in this session. */
+    list(): string[];
+}
+/** Builds a session-local micro definition without registering it. */
+export declare function defineMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(input: TsMicroDefinitionInput<TArgs, TReturn>): DefinedMicro<TArgs, TReturn>;
+export {};

package/dist/micro.js

@@ -0,0 +1,160 @@
+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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,66 @@
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nativeBindingName, platformKey } from './resolve-bin.js';
+function existsFile(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function loadFromPath(bindingPath) {
+    const require = createRequire(import.meta.url);
+    return require(bindingPath);
+}
+function monorepoBindingPath(key) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, '../../..');
+    const profile = process.env.YYDB_NATIVE_PROFILE === 'debug' ? 'debug' : 'release';
+    const base = path.join(repoRoot, 'target', profile);
+    const candidates = process.platform === 'win32'
+        ? [path.join(base, 'yydb_napi.dll'), path.join(base, 'yydb_napi.node')]
+        : [path.join(base, 'libyydb_napi.so'), path.join(base, 'libyydb_napi.dylib'), path.join(base, 'yydb_napi.node')];
+    for (const candidate of candidates) {
+        if (existsFile(candidate)) {
+            return candidate;
+        }
+    }
+    const staged = path.join(repoRoot, 'projects', 'packages', `yydb-${key}`, nativeBindingName(key));
+    return existsFile(staged) ? staged : null;
+}
+/** Load the platform native binding used by the `yydb` CLI. */
+export function loadNative() {
+    const fromEnv = process.env.YYDB_NATIVE?.trim();
+    if (fromEnv) {
+        if (!existsFile(fromEnv)) {
+            throw new Error(`YYDB_NATIVE points to missing binding: ${fromEnv}`);
+        }
+        return loadFromPath(path.resolve(fromEnv));
+    }
+    const key = platformKey();
+    if (key) {
+        const pkg = `@yydb/yydb-${key}`;
+        const require = createRequire(import.meta.url);
+        try {
+            const pkgJson = require.resolve(`${pkg}/package.json`);
+            const candidate = path.join(path.dirname(pkgJson), nativeBindingName(key));
+            if (existsFile(candidate)) {
+                return loadFromPath(candidate);
+            }
+        }
+        catch {
+            // optionalDependency not installed for this platform
+        }
+        const local = monorepoBindingPath(key);
+        if (local) {
+            return loadFromPath(local);
+        }
+    }
+    throw new Error('YYDB native binding not found. Install the matching optionalDependency ' +
+        `(@yydb/yydb-${key ?? '<platform>'}), set YYDB_NATIVE, or build ` +
+        '`cargo build -p yydb-napi --release` in this repo.');
+}

package/dist/resolve-bin.d.ts

@@ -1,10 +1,15 @@
 /// <reference types="node" />
-export type PlatformKey = "win32-x64" | "linux-x64" | "darwin-x64" | "darwin-arm64";
+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. */
+export declare function nativeBindingName(key: PlatformKey): string;
 /**
- * Resolve the `yydb` engine binary without asking the app developer to
- * configure downloads. Order: `YYDB_BIN` → optional platform package →
- * cargo `target/{release,debug}` (monorepo).
+ * 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;

package/dist/resolve-bin.js

@@ -1,24 +1,23 @@
-import { createRequire } from "node:module";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-const require = createRequire(import.meta.url);
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 /** Map Node platform/arch to optionalDependency package suffix. */
 export function platformKey(platform = process.platform, arch = process.arch) {
-    if (platform === "win32" && arch === "x64")
-        return "win32-x64";
-    if (platform === "linux" && arch === "x64")
-        return "linux-x64";
-    if (platform === "darwin" && arch === "x64")
-        return "darwin-x64";
-    if (platform === "darwin" && arch === "arm64")
-        return "darwin-arm64";
+    if (platform === 'win32' && arch === 'x64')
+        return 'win32-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
     return null;
 }
-function binaryName(platform = process.platform) {
-    return platform === "win32" ? "yydb.exe" : "yydb";
+/** Native binding filename inside each `@yydb/yydb-<platform>` package. */
+export function nativeBindingName(key) {
+    return `yydb.${key}.node`;
 }
-function existsExecutable(filePath) {
+function existsFile(filePath) {
     try {
         fs.accessSync(filePath, fs.constants.F_OK);
         return true;
@@ -28,42 +27,27 @@ function existsExecutable(filePath) {
     }
 }
 /**
- * Resolve the `yydb` engine binary without asking the app developer to
- * configure downloads. Order: `YYDB_BIN` → optional platform package →
- * cargo `target/{release,debug}` (monorepo).
+ * Resolve the TypeScript `yydb` CLI entry script.
+ * Order: `YYDB_CLI` → this package `dist/cli.js`.
  */
-export function resolveYydbBinary() {
-    const fromEnv = process.env.YYDB_BIN?.trim();
+export function resolveYydbCli() {
+    const fromEnv = process.env.YYDB_CLI?.trim();
     if (fromEnv) {
-        if (!existsExecutable(fromEnv)) {
-            throw new Error(`YYDB_BIN points to missing binary: ${fromEnv}`);
+        if (!existsFile(fromEnv)) {
+            throw new Error(`YYDB_CLI points to missing script: ${fromEnv}`);
         }
         return path.resolve(fromEnv);
     }
-    const key = platformKey();
-    if (key) {
-        const pkg = `@yydb/yydb-${key}`;
-        const name = binaryName();
-        try {
-            const pkgJson = require.resolve(`${pkg}/package.json`);
-            const candidate = path.join(path.dirname(pkgJson), name);
-            if (existsExecutable(candidate)) {
-                return candidate;
-            }
-        }
-        catch {
-            // optionalDependency not installed for this platform
-        }
-    }
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const repoRoot = path.resolve(here, "../../..");
-    for (const profile of ["release", "debug"]) {
-        const candidate = path.join(repoRoot, "target", profile, binaryName());
-        if (existsExecutable(candidate)) {
-            return candidate;
-        }
+    const candidate = path.join(here, 'cli.js');
+    if (!existsFile(candidate)) {
+        throw new Error('YYDB CLI script not found. Build `@yydb/yydb` (`pnpm --filter @yydb/yydb build`) or set YYDB_CLI.');
     }
-    throw new Error("YYDB engine binary not found. Install the matching optionalDependency " +
-        `(@yydb/yydb-${key ?? "<platform>"}), set YYDB_BIN, or build ` +
-        "`cargo build -p yydb-tools` in this repo.");
+    return candidate;
+}
+/**
+ * @deprecated Use {@link resolveYydbCli}. Kept for callers that still import this name.
+ */
+export function resolveYydbBinary() {
+    return resolveYydbCli();
 }

package/dist/udf-types.d.ts

@@ -0,0 +1,26 @@
+/** Phase-1 scalar UDF wire kinds aligned with `yydb-udf`. */
+export type UdfScalarKind = 'i64' | 'bool' | 'text' | 'null';
+/** Runtime type descriptor used in `defineMicro` contracts. */
+export interface UdfTypeDescriptor<T = unknown> {
+    readonly kind: UdfScalarKind;
+    /** Phantom type for author-side inference only. */
+    readonly _type?: T;
+}
+/** `i64` argument or return descriptor. */
+export declare function i64(): UdfTypeDescriptor<number>;
+/** `bool` argument or return descriptor. */
+export declare function bool(): UdfTypeDescriptor<boolean>;
+/** `text` argument or return descriptor. */
+export declare function text(): UdfTypeDescriptor<string>;
+/** `null` return descriptor. */
+export declare function nullType(): UdfTypeDescriptor<null>;
+/** Maps descriptor tuple types to positional argument types. */
+export type InferUdfArgs<T extends readonly UdfTypeDescriptor[]> = {
+    [K in keyof T]: T[K] extends UdfTypeDescriptor<infer V> ? V : never;
+};
+/** Maps a return descriptor to its value type. */
+export type InferUdfReturn<T extends UdfTypeDescriptor> = T extends UdfTypeDescriptor<infer V> ? V : never;
+/** Session micro effect surface (Phase 1: pure only). */
+export type MicroEffect = 'pure';
+/** Invocation mode stored with the definition for future batch host calls. */
+export type MicroInvocationMode = 'scalar' | 'batch';

package/dist/udf-types.js

@@ -0,0 +1,16 @@
+/** `i64` argument or return descriptor. */
+export function i64() {
+    return { kind: 'i64' };
+}
+/** `bool` argument or return descriptor. */
+export function bool() {
+    return { kind: 'bool' };
+}
+/** `text` argument or return descriptor. */
+export function text() {
+    return { kind: 'text' };
+}
+/** `null` return descriptor. */
+export function nullType() {
+    return { kind: 'null' };
+}