@silverbulletmd/silverbullet 2.8.1 → 2.10.0

package/client/space_lua/runtime.ts

@@ -5,6 +5,10 @@ import { isPromise, rpAll } from "./rp.ts";
 import { isNegativeZero, isTaggedFloat } from "./numeric.ts";
 import { isSqlNull } from "./sliq_null.ts";
 import { luaFormat } from "./stdlib/format.ts";
+import type {
+  LuaFunctionDocumentation,
+  LuaFunctionInfo,
+} from "../../plug-api/types/index.ts";
 
 export type LuaType =
   | "nil"
@@ -20,10 +24,19 @@ export type LuaType =
 export type LuaValue = any;
 export type JSValue = any;
 
+type LuaFunctionDefinitionMetadata = LuaFunctionDocumentation &
+  Partial<Pick<LuaFunctionInfo, "kind" | "name" | "source">>;
+
+export type LuaFunctionDefinition<Callback> = {
+  callback: Callback;
+} & LuaFunctionDefinitionMetadata;
+
 export interface ILuaFunction {
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue;
 
   asString(): string;
+
+  info?: LuaFunctionInfo;
 }
 
 export interface ILuaSettable {
@@ -453,12 +466,25 @@ export function singleResult(value: any): any {
 export class LuaFunction implements ILuaFunction {
   private capturedEnv: LuaEnv;
   funcHasGotos?: boolean;
+  info: LuaFunctionInfo;
 
   constructor(
     readonly body: LuaFunctionBody,
     closure: LuaEnv,
+    info: Partial<LuaFunctionInfo> = {},
   ) {
     this.capturedEnv = closure;
+    const documentation = body.documentation ?? {};
+    this.info = {
+      kind: "lua",
+      source: { ...body.ctx },
+      ...documentation,
+      ...info,
+      parameters:
+        info.parameters ??
+        documentation.parameters ??
+        body.parameters.map((name) => ({ name })),
+    };
   }
 
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
@@ -482,10 +508,7 @@ export class LuaFunction implements ILuaFunction {
         for (let i = 0; i < varargStart; i++) {
           env.setLocal(params[i], resolvedArgs[i] ?? null);
         }
-        env.setLocal(
-          "...",
-          new LuaMultiRes(resolvedArgs.slice(varargStart)),
-        );
+        env.setLocal("...", new LuaMultiRes(resolvedArgs.slice(varargStart)));
       } else {
         // Non-variadic: bind all named params directly
         for (let i = 0; i < params.length; i++) {
@@ -565,7 +588,26 @@ function mapFunctionReturnValue(values: any[]): any {
 }
 
 export class LuaNativeJSFunction implements ILuaFunction {
-  constructor(readonly fn: (...args: JSValue[]) => JSValue) {}
+  readonly fn: (...args: JSValue[]) => JSValue;
+  public info: LuaFunctionInfo;
+
+  constructor(
+    definition:
+      | ((...args: JSValue[]) => JSValue)
+      | LuaFunctionDefinition<(...args: JSValue[]) => JSValue>,
+  ) {
+    if (typeof definition === "function") {
+      this.fn = definition;
+      this.info = { kind: "builtin" };
+    } else {
+      const { callback, ...info } = definition;
+      this.fn = callback;
+      this.info = {
+        kind: "builtin",
+        ...info,
+      };
+    }
+  }
 
   // Performs automatic conversion between Lua and JS values for arguments, but not for return values
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
@@ -595,9 +637,28 @@ export class LuaNativeJSFunction implements ILuaFunction {
 }
 
 export class LuaBuiltinFunction implements ILuaFunction {
+  readonly fn: (sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue;
+  public info: LuaFunctionInfo;
+
   constructor(
-    readonly fn: (sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue,
-  ) {}
+    definition:
+      | ((sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue)
+      | LuaFunctionDefinition<
+          (sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue
+        >,
+  ) {
+    if (typeof definition === "function") {
+      this.fn = definition;
+      this.info = { kind: "builtin" };
+    } else {
+      const { callback, ...info } = definition;
+      this.fn = callback;
+      this.info = {
+        kind: "builtin",
+        ...info,
+      };
+    }
+  }
 
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
     // _CTX is already available via the stack frame
@@ -1313,11 +1374,9 @@ export function luaSet(
     const k = toNumKey(normKey);
     const jsVal = luaValueToJS(value, sf);
     if (isPromise(jsVal)) {
-      return (jsVal as Promise<any>).then(
-        (v) => {
-          (obj as Record<string | number, any>)[k] = v;
-        },
-      );
+      return (jsVal as Promise<any>).then((v) => {
+        (obj as Record<string | number, any>)[k] = v;
+      });
     }
     (obj as Record<string | number, any>)[k] = jsVal;
   }
@@ -1492,16 +1551,18 @@ export function luaCall(
 
 export function luaEquals(a: any, b: any): boolean {
   // Normalize nil variants (null, undefined, SQL NULL) to null
-  const an = (a === null || a === undefined || isSqlNull(a))
-    ? null
-    : isTaggedFloat(a)
-    ? a.value
-    : a;
-  const bn = (b === null || b === undefined || isSqlNull(b))
-    ? null
-    : isTaggedFloat(b)
-    ? b.value
-    : b;
+  const an =
+    a === null || a === undefined || isSqlNull(a)
+      ? null
+      : isTaggedFloat(a)
+        ? a.value
+        : a;
+  const bn =
+    b === null || b === undefined || isSqlNull(b)
+      ? null
+      : isTaggedFloat(b)
+        ? b.value
+        : b;
   return an === bn;
 }
 

package/client/space_lua/stdlib/crypto.ts

@@ -2,9 +2,14 @@ import { LuaBuiltinFunction, LuaTable } from "../runtime.ts";
 import { hashSHA256 } from "../../../plug-api/lib/crypto.ts";
 
 export const cryptoApi = new LuaTable({
-  sha256: new LuaBuiltinFunction(
-    (_sf, s: string | Uint8Array): Promise<string> => {
+  sha256: new LuaBuiltinFunction({
+    callback: (_sf, s: string | Uint8Array): Promise<string> => {
       return hashSHA256(s);
     },
-  ),
+    description: "Computes the SHA-256 digest of a string or byte buffer.",
+    parameters: [
+      { name: "data", type: "string|bytes", description: "Data to hash." },
+    ],
+    returns: [{ type: "string", description: "Hexadecimal SHA-256 digest." }],
+  }),
 });

package/client/space_lua/stdlib/encoding.ts

@@ -2,18 +2,36 @@ import { LuaBuiltinFunction, LuaTable } from "../runtime.ts";
 import { base64Decode, base64Encode } from "../../../plug-api/lib/crypto.ts";
 
 export const encodingApi = new LuaTable({
-  base64Encode: new LuaBuiltinFunction(
-    (_sf, s: string | Uint8Array): string => {
+  base64Encode: new LuaBuiltinFunction({
+    callback: (_sf, s: string | Uint8Array): string => {
       return base64Encode(s);
     },
-  ),
-  base64Decode: new LuaBuiltinFunction((_sf, s: string): Uint8Array => {
-    return base64Decode(s);
+    description: "Encodes a string or byte buffer as Base64.",
+    parameters: [{ name: "data", type: "string|bytes" }],
+    returns: [{ type: "string", description: "Base64-encoded data." }],
   }),
-  utf8Encode: new LuaBuiltinFunction((_sf, s: string): Uint8Array => {
-    return new TextEncoder().encode(s);
+  base64Decode: new LuaBuiltinFunction({
+    callback: (_sf, s: string): Uint8Array => {
+      return base64Decode(s);
+    },
+    description: "Decodes a Base64 string into a byte buffer.",
+    parameters: [{ name: "encoded", type: "string" }],
+    returns: [{ type: "bytes", description: "Decoded bytes." }],
+  }),
+  utf8Encode: new LuaBuiltinFunction({
+    callback: (_sf, s: string): Uint8Array => {
+      return new TextEncoder().encode(s);
+    },
+    description: "Encodes a UTF-8 string into a byte buffer.",
+    parameters: [{ name: "value", type: "string" }],
+    returns: [{ type: "bytes", description: "UTF-8 encoded bytes." }],
   }),
-  utf8Decode: new LuaBuiltinFunction((_sf, data: Uint8Array): string => {
-    return new TextDecoder().decode(data);
+  utf8Decode: new LuaBuiltinFunction({
+    callback: (_sf, data: Uint8Array): string => {
+      return new TextDecoder().decode(data);
+    },
+    description: "Decodes a UTF-8 byte buffer into a string.",
+    parameters: [{ name: "data", type: "bytes" }],
+    returns: [{ type: "string", description: "Decoded text." }],
   }),
 });

package/client/space_lua/stdlib/js.ts

@@ -4,6 +4,7 @@ import {
   LuaTable,
   luaValueToJS,
 } from "../runtime.ts";
+import { fsEndpoint } from "../../spaces/constants.ts";
 
 export const jsApi = new LuaTable({
   /**
@@ -12,57 +13,171 @@ export const jsApi = new LuaTable({
    * @param args - The arguments to pass to the constructor.
    * @returns The new instance.
    */
-  new: new LuaBuiltinFunction((sf, constructorFn: any, ...args) => {
-    return new constructorFn(...args.map((v) => luaValueToJS(v, sf)));
+  new: new LuaBuiltinFunction({
+    callback: (sf, constructorFn: any, ...args) => {
+      return new constructorFn(...args.map((v) => luaValueToJS(v, sf)));
+    },
+    description: "Creates an instance of a JavaScript class.",
+    signatures: ["js.new(constructor, ...): userdata"],
+    parameters: [
+      {
+        name: "constructor",
+        type: "userdata",
+        description: "JavaScript constructor function.",
+      },
+      {
+        name: "...",
+        description: "Constructor arguments converted to JavaScript values.",
+      },
+    ],
+    returns: [{ type: "userdata", description: "New JavaScript instance." }],
+    examples: [{ code: 'local value = js.new(js.window.Date, "2024-03-14")' }],
   }),
   /**
    * Imports a JavaScript module.
    * @param url - The URL of the module to import.
    * @returns The imported module.
    */
-  import: new LuaBuiltinFunction(async (_sf, url) => {
-    let m = await import(url);
-    // Unwrap default if it exists
-    if (Object.keys(m).length === 1 && m.default) {
-      m = m.default;
-    }
-    return m;
+  import: new LuaBuiltinFunction({
+    callback: async (_sf, url) => {
+      let m = await import(url);
+      // Unwrap default if it exists
+      if (Object.keys(m).length === 1 && m.default) {
+        m = m.default;
+      }
+      return m;
+    },
+    description: "Dynamically imports a JavaScript module from a URL.",
+    parameters: [{ name: "url", type: "string", description: "Module URL." }],
+    returns: [
+      {
+        type: "userdata",
+        description: "Imported module, with a sole default export unwrapped.",
+      },
+    ],
+    examples: [
+      { code: 'local lib = js.import("https://esm.sh/lodash@4.17.21")' },
+    ],
   }),
-  eachIterable: new LuaBuiltinFunction((_sf, val) => {
-    const iterator = val[Symbol.asyncIterator]();
-    return async () => {
-      const result = await iterator.next();
-      if (result.done) {
-        return;
+  /**
+   * Like `js.import`, but takes a path to a file in the current space (e.g.
+   * "Library/foo/bar.js") and resolves it to its full same-origin `/.fs` URL
+   * before importing.
+   * @param path - Space-relative path to the JS module (leading "/" optional).
+   * @returns The imported module (with a sole `default` export unwrapped).
+   */
+  importFromSpace: new LuaBuiltinFunction({
+    callback: async (_sf, path: string) => {
+      const base = document.baseURI.replace(/\/*$/, "/");
+      const rel = String(path).replace(/^\/+/, "");
+      let m = await import(`${base}${fsEndpoint.slice(1)}/${rel}`);
+      // Unwrap default if it exists (same contract as `js.import`).
+      if (Object.keys(m).length === 1 && m.default) {
+        m = m.default;
       }
-      return result.value;
-    };
+      return m;
+    },
+    description:
+      "Imports a JavaScript module from a file in the current space.",
+    parameters: [
+      {
+        name: "path",
+        type: "string",
+        description:
+          "Space-relative module path, with an optional leading slash.",
+      },
+    ],
+    returns: [
+      {
+        type: "userdata",
+        description: "Imported module, with a sole default export unwrapped.",
+      },
+    ],
+    examples: [
+      { code: 'local acme = js.importFromSpace("Library/acme/acme.js")' },
+    ],
+  }),
+  eachIterable: new LuaBuiltinFunction({
+    callback: (_sf, val) => {
+      const iterator = val[Symbol.asyncIterator]();
+      return async () => {
+        const result = await iterator.next();
+        if (result.done) {
+          return;
+        }
+        return result.value;
+      };
+    },
+    description: "Creates a Lua iterator over a JavaScript async iterable.",
+    parameters: [
+      {
+        name: "iterable",
+        type: "userdata",
+        description: "JavaScript async iterable.",
+      },
+    ],
+    returns: [
+      {
+        type: "function",
+        description: "Iterator yielding successive JavaScript values.",
+      },
+    ],
+    examples: [
+      {
+        code: "for value in js.eachIterable(someJsAsyncIterable) do\n  print(value)\nend",
+      },
+    ],
   }),
   /**
    * Converts a JavaScript value to a Lua value.
    * @param val - The JavaScript value to convert.
    * @returns The Lua value.
    */
-  tolua: new LuaBuiltinFunction((_sf, val) => jsToLuaValue(val)),
+  tolua: new LuaBuiltinFunction({
+    callback: (_sf, val) => jsToLuaValue(val),
+    description: "Converts a JavaScript value to its Lua representation.",
+    parameters: [
+      { name: "value", description: "JavaScript value to convert." },
+    ],
+    returns: [{ description: "Converted Lua value." }],
+    examples: [{ code: "local luaTable = js.tolua(jsArray)" }],
+  }),
   /**
    * Converts a Lua value to a JavaScript value.
    * @param val - The Lua value to convert.
    * @returns The JavaScript value.
    */
-  tojs: new LuaBuiltinFunction((sf, val) => luaValueToJS(val, sf)),
+  tojs: new LuaBuiltinFunction({
+    callback: (sf, val) => luaValueToJS(val, sf),
+    description: "Converts a Lua value to its JavaScript representation.",
+    parameters: [{ name: "value", description: "Lua value to convert." }],
+    returns: [{ description: "Converted JavaScript value." }],
+    examples: [{ code: "local jsArray = js.tojs({1, 2, 3})" }],
+  }),
   /**
    * Logs a message to the console.
    * @param args - The arguments to log.
    */
-  log: new LuaBuiltinFunction((_sf, ...args) => {
-    console.log(...args);
+  log: new LuaBuiltinFunction({
+    callback: (_sf, ...args) => {
+      console.log(...args);
+    },
+    description: "Logs values to the JavaScript console.",
+    parameters: [{ name: "...", description: "Values to log." }],
+    examples: [{ code: 'js.log("User data:", {name = "Ada"})' }],
   }),
   /**
    * Converts a Lua value to a JSON string.
    * @param val - The Lua value to convert.
    * @returns The JSON string.
    */
-  stringify: new LuaBuiltinFunction((_sf, val) => JSON.stringify(val)),
+  stringify: new LuaBuiltinFunction({
+    callback: (_sf, val) => JSON.stringify(val),
+    description: "Serializes a value as JSON using JavaScript semantics.",
+    parameters: [{ name: "value", description: "Value to serialize." }],
+    returns: [{ type: "string", description: "JSON representation." }],
+    examples: [{ code: "print(js.stringify({1, 2, 3})) -- [1,2,3]" }],
+  }),
 
   // Expose the global window object
   window: globalThis,

package/client/space_lua/stdlib/load.ts

@@ -5,7 +5,7 @@ import {
   type LuaStackFrame,
   type LuaValue,
 } from "../runtime.ts";
-import { parse } from "../parse.ts";
+import { parseBlock } from "../parse.ts";
 import { evalStatement } from "../eval.ts";
 
 // Returns a function (callable chunk) or (nil, "error message") pair.
@@ -13,7 +13,7 @@ export function luaLoad(code: LuaValue, sf: LuaStackFrame): LuaValue {
   const s = typeof code === "string" ? code : String(code);
 
   try {
-    const block = parse(s, sf.astCtx || {});
+    const block = parseBlock(s, sf.astCtx || {});
     const globalEnvMaybe = sf.threadLocal.get("_GLOBAL");
 
     // Be vocal when no _GLOBAL is set
@@ -24,22 +24,31 @@ export function luaLoad(code: LuaValue, sf: LuaStackFrame): LuaValue {
 
     const globalEnv: LuaEnv = globalEnvMaybe as LuaEnv;
 
-    const runner = new LuaBuiltinFunction(async (innerSf: LuaStackFrame) => {
-      const res = await evalStatement(block, globalEnv, innerSf, true);
-      if (res === undefined) {
-        return null;
-      } else {
-        if (res && typeof res === "object" && (res as any).ctrl === "return") {
-          return new LuaMultiRes((res as any).values);
+    const runner = new LuaBuiltinFunction({
+      callback: async (innerSf: LuaStackFrame) => {
+        const res = await evalStatement(block, globalEnv, innerSf, true);
+        if (res === undefined) {
+          return null;
+        } else {
+          if (
+            res &&
+            typeof res === "object" &&
+            (res as any).ctrl === "return"
+          ) {
+            return new LuaMultiRes((res as any).values);
+          }
+          if (res && typeof res === "object" && (res as any).ctrl === "break") {
+            throw new Error("break outside loop");
+          }
+          if (res && typeof res === "object" && (res as any).ctrl === "goto") {
+            throw new Error("unexpected goto signal");
+          }
+          return null;
         }
-        if (res && typeof res === "object" && (res as any).ctrl === "break") {
-          throw new Error("break outside loop");
-        }
-        if (res && typeof res === "object" && (res as any).ctrl === "goto") {
-          throw new Error("unexpected goto signal");
-        }
-        return null;
-      }
+      },
+      description: "Executes the Lua chunk compiled by `load`.",
+      signatures: ["function(...)"],
+      returns: [{ description: "Values returned by the compiled chunk." }],
     });
 
     return runner;