@lunora/bindings 1.0.0-alpha.2 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/bindings",
-  "version": "1.0.0-alpha.2",
+  "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",