@silverbulletmd/silverbullet 2.9.0 → 2.10.0

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

@@ -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;