@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/space_lua/stdlib/format.ts

@@ -56,7 +56,6 @@ function parseSpec(
     }
   }
 
-  // Parse width
   let width = 0;
   if (i < len && fmt.charCodeAt(i) === 42) {
     // '*'
@@ -69,7 +68,6 @@ function parseSpec(
     }
   }
 
-  // Parse precision
   let hasPrec = false;
   let prec = 0;
   if (i < len && fmt.charCodeAt(i) === 46) {
@@ -183,7 +181,6 @@ function formatInt(n: number, spec: FormatSpec): string {
 
   if (upper) digits = digits.toUpperCase();
 
-  // Precision
   if (spec.hasPrec) {
     if (spec.prec === 0 && v === 0) {
       digits = "";
@@ -192,7 +189,6 @@ function formatInt(n: number, spec: FormatSpec): string {
     }
   }
 
-  // Alt flag
   let prefix = "";
   if (spec.flags & FLAG_HASH) {
     if (base === 8 && (digits.length === 0 || digits.charCodeAt(0) !== 48)) {
@@ -277,7 +273,6 @@ function formatFloat(n: number, spec: FormatSpec): string {
   // Alt flag for 'f'/'e': ensure decimal point exists
   if (spec.flags & FLAG_HASH && lower !== 103) {
     if (body.indexOf(".") === -1) {
-      // Insert dot before 'e' if present, else append
       const eIdx = body.indexOf("e");
       const EIdx = body.indexOf("E");
       const expIdx = eIdx !== -1 ? eIdx : EIdx;
@@ -348,7 +343,6 @@ function stripTrailingZerosG(s: string): string {
     // '0'
     end--;
   }
-  // Remove dot if nothing after it
   if (end === dotIdx + 1) {
     end = dotIdx;
   }
@@ -452,13 +446,11 @@ function hexFloatBody(abs: number, spec: FormatSpec): string {
   let mantBits: bigint;
 
   if (biasedExp === 0) {
-    // Subnormal
     if (frac === 0n) return "0x0p+0";
     const shift = 52 - bitLength(frac) + 1;
     mantBits = frac << BigInt(shift);
     exponent = -1022 - shift;
   } else {
-    // Normal
     exponent = biasedExp - 1023;
     mantBits = frac | (1n << 52n);
   }
@@ -680,8 +672,6 @@ export function luaFormat(fmt: string, ...args: any[]): string {
   while (i < len) {
     const c = fmt.charCodeAt(i);
     if (c !== 37) {
-      // not '%'
-      // Fast path: scan for next '%' or end
       let j = i + 1;
       while (j < len && fmt.charCodeAt(j) !== 37) j++;
       out += fmt.slice(i, j);
@@ -689,7 +679,6 @@ export function luaFormat(fmt: string, ...args: any[]): string {
       continue;
     }
 
-    // '%' found
     i++;
     if (i >= len) {
       throw new Error("invalid format (ends with '%')");
@@ -705,7 +694,6 @@ export function luaFormat(fmt: string, ...args: any[]): string {
     const { spec, end } = parseSpec(fmt, i);
     i = end + 1;
 
-    // Resolve `*` width and precision from args
     let width = spec.width;
     if (width === -1) {
       width = Number(args[ai++]) || 0;

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,58 +13,170 @@ 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);
+      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

@@ -16,7 +16,6 @@ export function luaLoad(code: LuaValue, sf: LuaStackFrame): LuaValue {
     const block = parseBlock(s, sf.astCtx || {});
     const globalEnvMaybe = sf.threadLocal.get("_GLOBAL");
 
-    // Be vocal when no _GLOBAL is set
     if (!globalEnvMaybe) {
       console.warn("load() called without _GLOBAL in thread-local environment");
       return new LuaMultiRes([null, "Global environment not set"]);
@@ -24,22 +23,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;