@volter/world-core 2.0.0 → 2.0.1

package/dist/src/redis/index.d.ts

@@ -0,0 +1,2 @@
+export * from './engine.js';
+export * from './lua.js';

package/dist/src/redis/index.js

@@ -0,0 +1,6 @@
+// THE KERNEL'S REDIS LIBRARY (`@volter/world-core/redis`): Redis's command semantics over the World's tree and its Lua
+// interpreter. Shared by every pack that serves a Redis (the upstash
+// pack's REST envelope, the redis pack's own protocol), each through its dialect; the kernel names no vendor.
+// docs/contributing/architecture.md, "Other wires: lanes, headers and line protocols".
+export * from "./engine.js";
+export * from "./lua.js";

package/dist/src/redis/lua.d.ts

@@ -0,0 +1,153 @@
+/** A Lua runtime/parse error. Surfaces to the caller as a Redis script error, never as a result. */
+export declare class LuaError extends Error {
+    constructor(message: string);
+}
+/** A library's null that is not nil (lua-cjson's `cjson.null`, a lightuserdata in Redis): a value a table can hold,
+ *  and nil when a script returns it to Redis. */
+export declare const LUA_NULL: LuaValue;
+/** A Lua table. Array part + hash part, exactly like the real thing (1-based array indices). */
+export declare class LuaTable {
+    readonly map: Map<string | number | boolean, LuaValue>;
+    get(k: LuaValue): LuaValue;
+    set(k: LuaValue, v: LuaValue): void;
+    /** A non-nil value at a non-nil key. */
+    private store;
+    /** `#t` — the border of the array part: the largest n where t[1..n] are all non-nil. */
+    get length(): number;
+    static fromArray(values: LuaValue[]): LuaTable;
+    toArray(): LuaValue[];
+}
+export type LuaFunction = (args: LuaValue[]) => LuaValue[];
+/** `null` stands for Lua `nil` (JS `undefined` is never used as a value in this interpreter). */
+export type LuaValue = null | boolean | number | string | LuaTable | LuaFunction;
+type TokKind = 'name' | 'number' | 'string' | 'op' | 'keyword' | 'eof';
+type Token = {
+    kind: TokKind;
+    value: string;
+    line: number;
+};
+export declare function tokenize(src: string): Token[];
+type Expr = {
+    t: 'nil';
+} | {
+    t: 'true';
+} | {
+    t: 'false';
+} | {
+    t: 'num';
+    v: number;
+} | {
+    t: 'str';
+    v: string;
+} | {
+    t: 'name';
+    v: string;
+} | {
+    t: 'index';
+    obj: Expr;
+    key: Expr;
+} | {
+    t: 'call';
+    fn: Expr;
+    args: Expr[];
+    line?: number;
+} | {
+    t: 'bin';
+    op: string;
+    l: Expr;
+    r: Expr;
+} | {
+    t: 'un';
+    op: string;
+    e: Expr;
+} | {
+    t: 'table';
+    array: Expr[];
+    pairs: Array<{
+        k: Expr;
+        v: Expr;
+    }>;
+} | {
+    t: 'func';
+    params: string[];
+    body: Stat[];
+};
+type Stat = {
+    t: 'local';
+    names: string[];
+    exprs: Expr[];
+} | {
+    t: 'assign';
+    targets: Expr[];
+    exprs: Expr[];
+} | {
+    t: 'callstat';
+    call: Expr;
+} | {
+    t: 'if';
+    branches: Array<{
+        cond: Expr;
+        body: Stat[];
+    }>;
+    orelse: Stat[] | null;
+} | {
+    t: 'while';
+    cond: Expr;
+    body: Stat[];
+} | {
+    t: 'repeat';
+    body: Stat[];
+    cond: Expr;
+} | {
+    t: 'fornum';
+    name: string;
+    from: Expr;
+    to: Expr;
+    step: Expr | null;
+    body: Stat[];
+} | {
+    t: 'forin';
+    names: string[];
+    exprs: Expr[];
+    body: Stat[];
+} | {
+    t: 'do';
+    body: Stat[];
+} | {
+    t: 'return';
+    exprs: Expr[];
+} | {
+    t: 'break';
+};
+/** Parse Lua source into a chunk. Exported so a test can prove a bad script fails at PARSE time. */
+export declare function parseLua(src: string): Stat[];
+export declare function luaTruthy(v: LuaValue): boolean;
+export declare function luaTypeName(v: LuaValue): string;
+/** Lua 5.1's `%.14g` number formatting — `3` prints as "3", not "3.0". */
+export declare function numberToLuaString(n: number): string;
+/** `tonumber`, exactly: a number passes through, a numeric string converts, anything else is nil. */
+export declare function luaToNumber(v: LuaValue, base?: number): LuaValue;
+/** What the host must supply: a synchronous `redis.call`, plus KEYS/ARGV. */
+export type LuaHost = {
+    /** Run one Redis command, called from the script's line `line`. MUST throw to abort the script the way `redis.call` does. */
+    call: (args: string[], line: number) => LuaValue;
+    keys: string[];
+    argv: string[];
+    /** The wire's environment, installed after the standard library so it may replace it: it names the command API
+     *  (`commandApi`: call, pcall, error_reply, status_reply, sha1hex, log…) as scripts call it — Redis's scripts
+     *  call it `redis` and `server` — and adds the runtime libraries its server loads (lua-libs.ts). */
+    extend?: (globals: {
+        get(name: string): LuaValue;
+        set(name: string, value: LuaValue): void;
+        commandApi: LuaTable;
+    }) => void;
+    /** How a Lua number becomes a `redis.call` argument; truncated toward zero when absent. */
+    numberArg: (n: number) => string;
+};
+/** Lua `==`: same type required (no string/number coercion); tables compare by identity. */
+export declare function luaEquals(l: LuaValue, r: LuaValue): boolean;
+/** Parse + run a script. Returns the Lua value the chunk returned (or `nil`). */
+export declare function runLua(script: string, host: LuaHost): LuaValue;
+/** The SHA1 real Redis keys the script cache by — the same hex digest `SCRIPT LOAD` returns. */
+export declare function luaScriptSha1(script: string): string;
+export {};