@silverbulletmd/silverbullet 2.9.0 → 2.10.0

package/client/plugos/syscalls/datastore.ts

@@ -25,65 +25,171 @@ export function dataStoreReadSyscalls(
   clientSystem: ClientSystem,
 ): SysCallMapping {
   return {
-    "datastore.batchGet": (
-      _ctx,
-      keys: KvKey[],
-    ): Promise<(any | undefined)[]> => {
-      return ds.batchGet(keys);
+    "datastore.batchGet": {
+      callback: (_ctx, keys: KvKey[]): Promise<(any | undefined)[]> => {
+        return ds.batchGet(keys);
+      },
+      description: "Gets multiple values from the key-value store.",
+      parameters: [
+        { name: "keys", type: "table", description: "List of keys to read." },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Values in key order, with nil for missing keys.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local values = datastore.batchGet({{"user", "1"}, {"user", "2"}})',
+        },
+      ],
     },
 
-    "datastore.get": (_ctx, key: KvKey): Promise<any | null> => {
-      return ds.get(key);
+    "datastore.get": {
+      callback: (_ctx, key: KvKey): Promise<any | null> => {
+        return ds.get(key);
+      },
+      description: "Gets a value from the key-value store.",
+      parameters: [
+        { name: "key", type: "table", description: "Key segments." },
+      ],
+      returns: [{ description: "Stored value, or nil when absent." }],
+      examples: [{ code: 'local user = datastore.get({"user", "123"})' }],
     },
 
-    "datastore.query": async (_ctx, options: KvQueryOptions): Promise<KV[]> => {
-      const results: KV[] = [];
-      for await (const item of ds.query(options)) {
-        results.push(item);
-      }
-      return results;
+    "datastore.query": {
+      callback: async (_ctx, options: KvQueryOptions): Promise<KV[]> => {
+        const results: KV[] = [];
+        for await (const item of ds.query(options)) {
+          results.push(item);
+        }
+        return results;
+      },
+      description:
+        "Queries key-value entries, optionally restricted to a key prefix.",
+      parameters: [
+        {
+          name: "options",
+          type: "table",
+          description: "Query options, including an optional prefix.",
+        },
+      ],
+      returns: [{ type: "table", description: "Matching key-value entries." }],
     },
 
-    "datastore.queryLua": async (
-      _ctx,
-      prefix: string[],
-      query: LuaCollectionQuery,
-      scopeVariables?: Record<string, any>,
-    ): Promise<any[]> => {
-      const sf = LuaStackFrame.createWithGlobalEnv(
-        clientSystem.spaceLuaEnv.env,
-      );
-      let env = clientSystem.spaceLuaEnv.env;
-      if (scopeVariables) {
-        env = new LuaEnv(clientSystem.spaceLuaEnv.env);
-        for (const [key, value] of Object.entries(scopeVariables)) {
-          env.setLocal(key, jsToLuaValue(value));
+    "datastore.queryLua": {
+      callback: async (
+        _ctx,
+        prefix: string[],
+        query: LuaCollectionQuery,
+        scopeVariables?: Record<string, any>,
+      ): Promise<any[]> => {
+        const sf = LuaStackFrame.createWithGlobalEnv(
+          clientSystem.spaceLuaEnv.env,
+        );
+        let env = clientSystem.spaceLuaEnv.env;
+        if (scopeVariables) {
+          env = new LuaEnv(clientSystem.spaceLuaEnv.env);
+          for (const [key, value] of Object.entries(scopeVariables)) {
+            env.setLocal(key, jsToLuaValue(value));
+          }
         }
-      }
-      return (await queryLua<any>(ds.kv, prefix, query, env, sf)).map((item) =>
-        luaValueToJS(item, sf),
-      );
+        return (await queryLua<any>(ds.kv, prefix, query, env, sf)).map(
+          (item) => luaValueToJS(item, sf),
+        );
+      },
+      description: "Runs a Space Lua collection query over a key prefix.",
+      parameters: [
+        {
+          name: "prefix",
+          type: "table",
+          description: "Key prefix to query.",
+        },
+        {
+          name: "query",
+          type: "table",
+          description: "Parsed collection query.",
+        },
+        {
+          name: "scopeVariables",
+          type: "table",
+          description: "Additional variables available to the query.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Query results converted to Lua values.",
+        },
+      ],
     },
   };
 }
 
 export function dataStoreWriteSyscalls(ds: DataStore): SysCallMapping {
   return {
-    "datastore.delete": (_ctx, key: KvKey) => {
-      console.log("Deleting key", key);
-      return ds.delete(key);
+    "datastore.delete": {
+      callback: (_ctx, key: KvKey) => {
+        console.log("Deleting key", key);
+        return ds.delete(key);
+      },
+      description: "Deletes a value from the key-value store.",
+      parameters: [
+        { name: "key", type: "table", description: "Key segments." },
+      ],
+      examples: [{ code: 'datastore.delete({"user", "123"})' }],
     },
 
-    "datastore.set": (_ctx, key: KvKey, value: any) => {
-      return ds.set(key, value);
+    "datastore.set": {
+      callback: (_ctx, key: KvKey, value: any) => {
+        return ds.set(key, value);
+      },
+      description: "Sets a value in the key-value store.",
+      parameters: [
+        { name: "key", type: "table", description: "Key segments." },
+        { name: "value", description: "Value to store." },
+      ],
+      examples: [{ code: 'datastore.set({"user", "123"}, {name = "John"})' }],
     },
 
-    "datastore.batchSet": (_ctx, kvs: KV[]) => {
-      return ds.batchSet(kvs);
+    "datastore.batchSet": {
+      callback: (_ctx, kvs: KV[]) => {
+        return ds.batchSet(kvs);
+      },
+      description: "Sets multiple key-value entries in one operation.",
+      parameters: [
+        {
+          name: "entries",
+          type: "table",
+          description: "Entries with key and value fields.",
+        },
+      ],
+      examples: [
+        {
+          code: 'datastore.batchSet({\n  {key = {"user", "1"}, value = {name = "Alice"}},\n  {key = {"user", "2"}, value = {name = "Bob"}},\n})',
+        },
+      ],
     },
 
-    "datastore.batchDelete": (_ctx, keys: KvKey[]) => {
-      return ds.batchDelete(keys);
+    "datastore.batchDelete": {
+      callback: (_ctx, keys: KvKey[]) => {
+        return ds.batchDelete(keys);
+      },
+      description: "Deletes multiple values from the key-value store.",
+      parameters: [
+        {
+          name: "keys",
+          type: "table",
+          description: "List of keys to delete.",
+        },
+      ],
+      examples: [
+        {
+          code: 'datastore.batchDelete({{"user", "1"}, {"user", "2"}})',
+        },
+      ],
     },
   };
 }