@lunora/bindings 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/kv/index.d.mts

@@ -174,4 +174,98 @@ interface Kv {
 */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createKv: (options: LunoraKvOptions) => Kv;
-export { type KVNamespaceLike, type Kv, type KvGetOptions, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, scopeKey };
+/** One KV namespace as the studio's KV browser surfaces it (mirrors the runtime's KvNamespaceSummary). */
+interface KvNamespaceSummaryLike {
+  binding: string;
+}
+/** One key entry as surfaced by the KV admin browser (mirrors the runtime's KvKeyEntry). */
+interface KvKeyEntryLike {
+  expiration?: number;
+  metadata?: unknown;
+  name: string;
+}
+/** A paginated page of KV keys (mirrors the runtime's KvKeyListResult). */
+interface KvKeyListResultLike {
+  cursor?: string;
+  keys: KvKeyEntryLike[];
+  listComplete: boolean;
+}
+/** A value together with its metadata (mirrors the runtime's KvValueResult). */
+interface KvValueResultLike {
+  metadata: unknown;
+  value: null | string;
+}
+/**
+* The structural shape of a KV introspector — mirrors `KvIntrospector` from
+* `@lunora/runtime` without importing it, keeping the dependency graph clean.
+*/
+interface KvIntrospectorLike {
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResultLike>;
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResultLike>;
+  listNamespaces: () => Promise<KvNamespaceSummaryLike[]>;
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/** Construction options for {@link createKvIntrospector}. */
+interface CreateKvIntrospectorOptions {
+  /**
+  * Map of binding name → bound KV namespace. Each entry becomes one
+  * namespace the studio can browse. Example:
+  * ```ts
+  * createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } })
+  * ```
+  */
+  namespaces: Record<string, KVNamespaceLike>;
+}
+/**
+* Build a `KvIntrospector`-compatible object from a map of bound KV namespaces.
+* Pass the result as `kvIntrospector` on `WorkerOptions` to enable the studio's
+* KV browser (`/_lunora/admin/kv/*` endpoints).
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } }),
+* });
+* ```
+*/
+declare const createKvIntrospector: (options: CreateKvIntrospectorOptions) => KvIntrospectorLike;
+/**
+* Zero-config KV introspector: scan a worker `env` for every bound Workers KV
+* namespace and register each under its binding name. Every `kv_namespaces` entry
+* in `wrangler.jsonc` then appears in the studio's KV browser automatically — no
+* hand-written `createKvIntrospector({ namespaces: … })` call, and any binding
+* name (not just `KV`) and any number of namespaces light up. Non-KV bindings
+* (R2, Durable Objects, queues, secrets, …) are skipped via {@link isKvNamespace}.
+*
+* Returns an introspector even when `env` holds no KV namespaces — its
+* `listNamespaces()` resolves to `[]`, so the studio renders an empty state
+* rather than a "not configured" error.
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospectorFromEnv(env),
+* });
+* ```
+*/
+declare const createKvIntrospectorFromEnv: (env: unknown) => KvIntrospectorLike;
+export { type CreateKvIntrospectorOptions, type KVNamespaceLike, type Kv, type KvGetOptions, type KvIntrospectorLike, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, createKvIntrospector, createKvIntrospectorFromEnv, scopeKey };

package/dist/kv/index.d.ts

@@ -174,4 +174,98 @@ interface Kv {
 */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createKv: (options: LunoraKvOptions) => Kv;
-export { type KVNamespaceLike, type Kv, type KvGetOptions, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, scopeKey };
+/** One KV namespace as the studio's KV browser surfaces it (mirrors the runtime's KvNamespaceSummary). */
+interface KvNamespaceSummaryLike {
+  binding: string;
+}
+/** One key entry as surfaced by the KV admin browser (mirrors the runtime's KvKeyEntry). */
+interface KvKeyEntryLike {
+  expiration?: number;
+  metadata?: unknown;
+  name: string;
+}
+/** A paginated page of KV keys (mirrors the runtime's KvKeyListResult). */
+interface KvKeyListResultLike {
+  cursor?: string;
+  keys: KvKeyEntryLike[];
+  listComplete: boolean;
+}
+/** A value together with its metadata (mirrors the runtime's KvValueResult). */
+interface KvValueResultLike {
+  metadata: unknown;
+  value: null | string;
+}
+/**
+* The structural shape of a KV introspector — mirrors `KvIntrospector` from
+* `@lunora/runtime` without importing it, keeping the dependency graph clean.
+*/
+interface KvIntrospectorLike {
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResultLike>;
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResultLike>;
+  listNamespaces: () => Promise<KvNamespaceSummaryLike[]>;
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/** Construction options for {@link createKvIntrospector}. */
+interface CreateKvIntrospectorOptions {
+  /**
+  * Map of binding name → bound KV namespace. Each entry becomes one
+  * namespace the studio can browse. Example:
+  * ```ts
+  * createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } })
+  * ```
+  */
+  namespaces: Record<string, KVNamespaceLike>;
+}
+/**
+* Build a `KvIntrospector`-compatible object from a map of bound KV namespaces.
+* Pass the result as `kvIntrospector` on `WorkerOptions` to enable the studio's
+* KV browser (`/_lunora/admin/kv/*` endpoints).
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } }),
+* });
+* ```
+*/
+declare const createKvIntrospector: (options: CreateKvIntrospectorOptions) => KvIntrospectorLike;
+/**
+* Zero-config KV introspector: scan a worker `env` for every bound Workers KV
+* namespace and register each under its binding name. Every `kv_namespaces` entry
+* in `wrangler.jsonc` then appears in the studio's KV browser automatically — no
+* hand-written `createKvIntrospector({ namespaces: … })` call, and any binding
+* name (not just `KV`) and any number of namespaces light up. Non-KV bindings
+* (R2, Durable Objects, queues, secrets, …) are skipped via {@link isKvNamespace}.
+*
+* Returns an introspector even when `env` holds no KV namespaces — its
+* `listNamespaces()` resolves to `[]`, so the studio renders an empty state
+* rather than a "not configured" error.
+* @example
+* ```ts
+* createWorker({
+*   // …
+*   kvIntrospector: createKvIntrospectorFromEnv(env),
+* });
+* ```
+*/
+declare const createKvIntrospectorFromEnv: (env: unknown) => KvIntrospectorLike;
+export { type CreateKvIntrospectorOptions, type KVNamespaceLike, type Kv, type KvGetOptions, type KvIntrospectorLike, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, createKvIntrospector, createKvIntrospectorFromEnv, scopeKey };

package/dist/kv/index.mjs

@@ -1 +1,2 @@
 export { createKv, scopeKey } from '../packem_shared/createKv-DTiSt216.mjs';
+export { createKvIntrospector, createKvIntrospectorFromEnv } from '../packem_shared/createKvIntrospector-BThrJVhP.mjs';

package/dist/packem_shared/{R2SqlError-DkQZ4Omg.mjs → R2SqlError-DlDd_SrE.mjs}

@@ -1,5 +1,5 @@
-import SelectBuilder from './SelectBuilder-BGXfCF0J.mjs';
-import { toText } from './Sql-CkDyJ_Sc.mjs';
+import SelectBuilder from './SelectBuilder-DHaXZwn_.mjs';
+import { ident, toText } from './Sql-DceGtcUd.mjs';
 
 const API_BASE = "https://api.sql.cloudflarestorage.com/api/v1/accounts";
 const inferColumns = (rows) => {
@@ -53,12 +53,14 @@ const createR2Sql = (config) => {
     };
   };
   return {
-    describe: async (table) => exec(`DESCRIBE ${table}`),
+    describe: async (table) => exec(`DESCRIBE ${ident(table)}`),
     explain: async (statement, options) => exec(`EXPLAIN ${options?.format === "json" ? "FORMAT JSON " : ""}${toText(statement)}`),
+    // `SelectBuilder`'s constructor validates the table reference (allowing an
+    // optional `[AS] alias`), so no pre-validation here.
     from: (table) => new SelectBuilder(exec, table),
     query: async (statement) => exec(toText(statement)),
     showDatabases: async () => exec("SHOW DATABASES"),
-    showTables: async (namespace) => exec(`SHOW TABLES IN ${namespace}`)
+    showTables: async (namespace) => exec(`SHOW TABLES IN ${ident(namespace)}`)
   };
 };
 

package/dist/packem_shared/{SelectBuilder-BGXfCF0J.mjs → SelectBuilder-DHaXZwn_.mjs}

@@ -1,6 +1,6 @@
-import { renderOrderTerm } from './asc-C6Jbaa6R.mjs';
-import SetOperation from './SetOperation-CGRu681M.mjs';
-import { toText, lit } from './Sql-CkDyJ_Sc.mjs';
+import { renderOrderTerm } from './asc-Cur-xO8v.mjs';
+import SetOperation from './SetOperation-RDHcxccj.mjs';
+import { tableRef, toText, lit } from './Sql-DceGtcUd.mjs';
 
 const JOIN_KEYWORDS = {
   cross: "CROSS JOIN",
@@ -24,7 +24,7 @@ class SelectBuilder {
   limitValue;
   constructor(exec, table) {
     this.exec = exec;
-    this.table = table;
+    this.table = tableRef(table);
   }
   /** The `SELECT` list. Omit/empty for `SELECT *`. Items are columns, expressions, or aliased window fragments (`fn.rowNumber().over(...).as("rk")`). */
   select(...items) {
@@ -156,7 +156,7 @@ class SelectBuilder {
     return this.distinctFlag ? "SELECT DISTINCT" : "SELECT";
   }
   addJoin(kind, table, on) {
-    this.joins.push({ kind, on, table });
+    this.joins.push({ kind, on, table: tableRef(table) });
     return this;
   }
   setOperation(operator, other) {

package/dist/packem_shared/{SetOperation-CGRu681M.mjs → SetOperation-RDHcxccj.mjs}

@@ -1,5 +1,5 @@
-import { renderOrderTerm } from './asc-C6Jbaa6R.mjs';
-import { lit } from './Sql-CkDyJ_Sc.mjs';
+import { renderOrderTerm } from './asc-Cur-xO8v.mjs';
+import { lit } from './Sql-DceGtcUd.mjs';
 
 const renderMember = (query) => {
   const text = query.toSQL();

package/dist/packem_shared/{Sql-CkDyJ_Sc.mjs → Sql-DceGtcUd.mjs}

@@ -1,4 +1,6 @@
 const quoteString = (value) => `'${value.replaceAll("'", "''")}'`;
+const IDENTIFIER_RE = /^\w+(?:\.\w+)*$/;
+const TABLE_REF_RE = /^\w+(?:\.\w+)*(?:\s+(?:as\s+)?\w+)?$/i;
 class Sql {
   text;
   constructor(text) {
@@ -11,6 +13,18 @@ class Sql {
 const isSql = (value) => value instanceof Sql;
 const raw = (text) => new Sql(text);
 const toText = (value) => isSql(value) ? value.text : value;
+const ident = (name) => {
+  if (typeof name !== "string" || !IDENTIFIER_RE.test(name)) {
+    throw new TypeError(`r2sql: invalid identifier ${JSON.stringify(name)} — expected dotted [A-Za-z0-9_] segments (e.g. "namespace.table").`);
+  }
+  return name;
+};
+const tableRef = (ref) => {
+  if (typeof ref !== "string" || !TABLE_REF_RE.test(ref)) {
+    throw new TypeError(`r2sql: invalid table reference ${JSON.stringify(ref)} — expected "namespace.table" with an optional "[AS] alias".`);
+  }
+  return ref;
+};
 const lit = (value) => {
   if (value === null || value === void 0) {
     return "NULL";
@@ -51,4 +65,4 @@ const sql = (strings, ...values) => {
 };
 const joinSql = (parts, separator) => new Sql(parts.map((part) => toText(part)).join(separator));
 
-export { Sql, isSql, joinSql, lit, raw, sql, toText };
+export { Sql, ident, isSql, joinSql, lit, raw, sql, tableRef, toText };

package/dist/packem_shared/{WindowExpression-C2vj7oNX.mjs → WindowExpression-Cg9s2xcr.mjs}

@@ -1,4 +1,4 @@
-import { Sql, lit } from './Sql-CkDyJ_Sc.mjs';
+import { Sql, lit } from './Sql-DceGtcUd.mjs';
 
 const IDENTIFIER = /^[A-Z_][\w$]*$/i;
 const assertIdent = (name) => {

package/dist/packem_shared/{WindowFunction-CuKHfZX3.mjs → WindowFunction-DA3pGC3N.mjs}

@@ -1,6 +1,6 @@
-import { renderOrderTerm } from './asc-C6Jbaa6R.mjs';
-import { lit, toText } from './Sql-CkDyJ_Sc.mjs';
-import WindowExpression from './WindowExpression-C2vj7oNX.mjs';
+import { renderOrderTerm } from './asc-Cur-xO8v.mjs';
+import { lit, toText } from './Sql-DceGtcUd.mjs';
+import WindowExpression from './WindowExpression-Cg9s2xcr.mjs';
 
 const toArray = (value) => {
   if (value === void 0) {

package/dist/packem_shared/{asc-C6Jbaa6R.mjs → asc-Cur-xO8v.mjs}

@@ -1,4 +1,4 @@
-import { Sql, toText } from './Sql-CkDyJ_Sc.mjs';
+import { Sql, toText } from './Sql-DceGtcUd.mjs';
 
 const asc = (expr) => {
   return { dir: "ASC", expr };

package/dist/packem_shared/createKvIntrospector-BThrJVhP.mjs

@@ -0,0 +1,75 @@
+const createKvIntrospector = (options) => {
+  const { namespaces } = options;
+  const resolveNamespace = (binding) => {
+    const ns = namespaces[binding];
+    if (ns === void 0) {
+      throw new Error(`@lunora/bindings/kv: no namespace registered under binding "${binding}"`);
+    }
+    return ns;
+  };
+  const listNamespaces = () => Promise.resolve(
+    Object.keys(namespaces).map((binding) => {
+      return { binding };
+    })
+  );
+  const listKeys = async (listOptions) => {
+    const ns = resolveNamespace(listOptions.namespace);
+    const result = await ns.list({ cursor: listOptions.cursor, limit: listOptions.limit, prefix: listOptions.prefix });
+    const keys = result.keys.map((entry) => {
+      return {
+        expiration: entry.expiration,
+        metadata: entry.metadata,
+        name: entry.name
+      };
+    });
+    return {
+      cursor: result.list_complete ? void 0 : result.cursor,
+      keys,
+      listComplete: result.list_complete
+    };
+  };
+  const getValue = async (getOptions) => {
+    const ns = resolveNamespace(getOptions.namespace);
+    const result = await ns.getWithMetadata(getOptions.key, "text");
+    return { metadata: result.metadata ?? null, value: result.value ?? null };
+  };
+  const putValue = async (putOptions) => {
+    const ns = resolveNamespace(putOptions.namespace);
+    await ns.put(putOptions.key, putOptions.value, {
+      expiration: putOptions.expiration,
+      expirationTtl: putOptions.expirationTtl,
+      metadata: putOptions.metadata
+    });
+  };
+  const deleteKey = async (deleteOptions) => {
+    const ns = resolveNamespace(deleteOptions.namespace);
+    await ns.delete(deleteOptions.key);
+  };
+  return {
+    deleteKey,
+    getValue,
+    listKeys,
+    listNamespaces,
+    putValue
+  };
+};
+const isKvNamespace = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.getWithMetadata === "function" && typeof candidate.list === "function" && typeof candidate.put === "function" && typeof candidate.delete === "function";
+};
+const createKvIntrospectorFromEnv = (env) => {
+  const namespaces = {};
+  if (typeof env === "object" && env !== null) {
+    for (const [binding, value] of Object.entries(env)) {
+      if (isKvNamespace(value)) {
+        namespaces[binding] = value;
+      }
+    }
+  }
+  return createKvIntrospector({ namespaces });
+};
+
+export { createKvIntrospector, createKvIntrospectorFromEnv };

package/dist/r2sql/index.mjs

@@ -1,7 +1,7 @@
-export { default as SelectBuilder } from '../packem_shared/SelectBuilder-BGXfCF0J.mjs';
-export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-DkQZ4Omg.mjs';
-export { asc, desc, renderOrderTerm } from '../packem_shared/asc-C6Jbaa6R.mjs';
-export { default as SetOperation } from '../packem_shared/SetOperation-CGRu681M.mjs';
-export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-CkDyJ_Sc.mjs';
-export { WindowFunction, fn } from '../packem_shared/WindowFunction-CuKHfZX3.mjs';
-export { default as WindowExpression } from '../packem_shared/WindowExpression-C2vj7oNX.mjs';
+export { default as SelectBuilder } from '../packem_shared/SelectBuilder-DHaXZwn_.mjs';
+export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-DlDd_SrE.mjs';
+export { asc, desc, renderOrderTerm } from '../packem_shared/asc-Cur-xO8v.mjs';
+export { default as SetOperation } from '../packem_shared/SetOperation-RDHcxccj.mjs';
+export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-DceGtcUd.mjs';
+export { WindowFunction, fn } from '../packem_shared/WindowFunction-DA3pGC3N.mjs';
+export { default as WindowExpression } from '../packem_shared/WindowExpression-Cg9s2xcr.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/bindings",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "description": "Lightweight Cloudflare binding helpers for Lunora — ctx.kv, ctx.images, ctx.analytics, ctx.pipelines, ctx.vectors, ctx.r2sql — one install, per-binding subpaths",
   "keywords": [
     "analytics",