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

package/dist/kv/index.d.mts

@@ -1,16 +1,16 @@
 /**
-* The value types Workers KV can store / return. Mirrors Cloudflare's
-* `KVNamespace` `get`/`put` body unions; declared here so the package stays
-* runtime-agnostic and the `*Like` interfaces don't pull in
-* `@cloudflare/workers-types` at runtime.
-*/
+ * The value types Workers KV can store / return. Mirrors Cloudflare's
+ * `KVNamespace` `get`/`put` body unions; declared here so the package stays
+ * runtime-agnostic and the `*Like` interfaces don't pull in
+ * `@cloudflare/workers-types` at runtime.
+ */
 type KvValue = ReadableStream | ArrayBuffer | ArrayBufferView | string;
 /** How a raw KV read should decode the stored value. Mirrors KV's `type` option. */
 type KvValueType = "text" | "json" | "arrayBuffer" | "stream";
 /**
-* Per-read options forwarded to the binding. `cacheTtl` is KV's edge-cache TTL
-* (seconds, min 60); `type` selects the decode mode for {@link Kv.getRaw}.
-*/
+ * Per-read options forwarded to the binding. `cacheTtl` is KV's edge-cache TTL
+ * (seconds, min 60); `type` selects the decode mode for {@link Kv.getRaw}.
+ */
 interface KvGetOptions {
   /** KV edge-cache TTL in seconds (minimum 60). Forwarded verbatim. */
   cacheTtl?: number;
@@ -18,23 +18,23 @@ interface KvGetOptions {
   type?: KvValueType;
 }
 /**
-* Minimal projection of Cloudflare's `KVNamespace`. Declared structurally so
-* unit tests can pass a plain `Map`-backed double; the real binding satisfies
-* the same shape. Mirrors `R2BucketLike` in `@lunora/storage`.
-*/
+ * Minimal projection of Cloudflare's `KVNamespace`. Declared structurally so
+ * unit tests can pass a plain `Map`-backed double; the real binding satisfies
+ * the same shape. Mirrors `R2BucketLike` in `@lunora/storage`.
+ */
 interface KVNamespaceLike {
   /** Delete a key. No-op if the key is absent. */
   delete: (key: string) => Promise<void>;
   /**
-  * Read a value. The real binding overloads on `options.type`; declared here
-  * as the broad union so a structural double need only return the value (or
-  * `null` when absent).
-  */
+   * Read a value. The real binding overloads on `options.type`; declared here
+   * as the broad union so a structural double need only return the value (or
+   * `null` when absent).
+   */
   get: (key: string, options?: KvGetOptions | KvValueType) => Promise<unknown>;
   /**
-  * Read a value together with its associated metadata. Returns
-  * `{ value: null, metadata: null }` when the key is absent.
-  */
+   * Read a value together with its associated metadata. Returns
+   * `{ value: null, metadata: null }` when the key is absent.
+   */
   getWithMetadata: (key: string, options?: KvGetOptions | KvValueType) => Promise<{
     metadata: unknown;
     value: unknown;
@@ -80,11 +80,11 @@ type KvNamespaceListResult<Metadata = unknown> = {
 /** Construction options for the `createKv` factory. */
 interface LunoraKvOptions {
   /**
-  * Optional per-instance key prefix applied to every operation (get/put/
-  * delete/list). Use for multi-tenant key namespacing — equivalent to
-  * calling the `scopeKey` helper on every key. Combined via `scopeKey`, so a
-  * `..` or NUL in the prefix is rejected.
-  */
+   * Optional per-instance key prefix applied to every operation (get/put/
+   * delete/list). Use for multi-tenant key namespacing — equivalent to
+   * calling the `scopeKey` helper on every key. Combined via `scopeKey`, so a
+   * `..` or NUL in the prefix is rejected.
+   */
   keyPrefix?: string;
   /** The bound KV namespace (`env.&lt;BINDING>`). */
   namespace: KVNamespaceLike;
@@ -98,9 +98,9 @@ interface KvPutOptions {
   /** Arbitrary metadata stored alongside the value (returned by `getWithMetadata`/`list`). */
   metadata?: unknown;
   /**
-  * When true, write `value` to KV verbatim (no `JSON.stringify`). `value`
-  * must already be a KV-writable type (string/ArrayBuffer/stream).
-  */
+   * When true, write `value` to KV verbatim (no `JSON.stringify`). `value`
+   * must already be a KV-writable type (string/ArrayBuffer/stream).
+   */
   raw?: boolean;
 }
 /** Options for {@link Kv.list}. */
@@ -117,9 +117,9 @@ interface KvListResult<Metadata = unknown> {
   /** Cursor for the next page; `undefined` when the listing is complete. */
   cursor?: string;
   /**
-  * The key names, with any instance `keyPrefix` stripped back off so callers
-  * see the same keys they wrote.
-  */
+   * The key names, with any instance `keyPrefix` stripped back off so callers
+   * see the same keys they wrote.
+   */
   keys: KvListKey<Metadata>[];
   /** True when this is the final page (no further `cursor`). */
   listComplete: boolean;
@@ -132,46 +132,140 @@ interface KvValueWithMetadata<Value, Metadata> {
   value: Value | null;
 }
 /**
-* The typed Workers KV client bound to `ctx.kv`. JSON-decodes/encodes by
-* default; a raw escape hatch ({@link Kv.getRaw} / `put(..., { raw: true })`)
-* handles text/binary/stream values.
-*/
+ * The typed Workers KV client bound to `ctx.kv`. JSON-decodes/encodes by
+ * default; a raw escape hatch ({@link Kv.getRaw} / `put(..., { raw: true })`)
+ * handles text/binary/stream values.
+ */
 interface Kv {
   /** Delete a key. No-op if absent. */
   delete: (key: string) => Promise<void>;
   /**
-  * Read a key and `JSON.parse` it into `T`. Returns `null` when the key is
-  * absent. Throws if the stored value isn't valid JSON — use
-  * {@link Kv.getRaw} for non-JSON values.
-  */
+   * Read a key and `JSON.parse` it into `T`. Returns `null` when the key is
+   * absent. Throws if the stored value isn't valid JSON — use
+   * {@link Kv.getRaw} for non-JSON values.
+   */
   get: <T = unknown>(key: string, options?: {
     cacheTtl?: number;
   }) => Promise<T | null>;
   /** Read a raw value with an explicit decode `type` (default `"text"`). Returns `null` when absent. */
   getRaw: <T = string>(key: string, options?: KvGetOptions) => Promise<T | null>;
   /**
-  * Read a key's JSON value together with its metadata. Returns
-  * `{ value: null, metadata: null }` when the key is absent.
-  */
+   * Read a key's JSON value together with its metadata. Returns
+   * `{ value: null, metadata: null }` when the key is absent.
+   */
   getWithMetadata: <T = unknown, M = unknown>(key: string, options?: {
     cacheTtl?: number;
   }) => Promise<KvValueWithMetadata<T, M>>;
   /** List keys (optionally `prefix`-filtered, paginated via `cursor`). */
   list: <M = unknown>(options?: KvListOptions) => Promise<KvListResult<M>>;
   /**
-  * Write `value` to `key`. JSON-stringifies `value` unless `options.raw` is
-  * set (in which case `value` must be a KV-writable type). Forwards
-  * `expirationTtl`/`expiration`/`metadata` to the binding.
-  */
+   * Write `value` to `key`. JSON-stringifies `value` unless `options.raw` is
+   * set (in which case `value` must be a KV-writable type). Forwards
+   * `expirationTtl`/`expiration`/`metadata` to the binding.
+   */
   put: <T = unknown>(key: string, value: T, options?: KvPutOptions) => Promise<void>;
 }
 /**
-* Compose a per-tenant key from a scope prefix and a caller-supplied key. Both
-* halves are validated — the prefix may not contain `..` or NUL either, and the
-* resulting key must stay under KV's length ceiling. Recommended for any
-* multi-tenant deployment so client-supplied keys can't address peer data.
-* Mirrors `scopeKey` from `@lunora/storage`.
-*/
+ * Compose a per-tenant key from a scope prefix and a caller-supplied key. Both
+ * halves are validated — the prefix may not contain `..` or NUL either, and the
+ * resulting key must stay under KV's length ceiling. Recommended for any
+ * multi-tenant deployment so client-supplied keys can't address peer data.
+ * Mirrors `scopeKey` from `@lunora/storage`.
+ */
 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

@@ -1,16 +1,16 @@
 /**
-* The value types Workers KV can store / return. Mirrors Cloudflare's
-* `KVNamespace` `get`/`put` body unions; declared here so the package stays
-* runtime-agnostic and the `*Like` interfaces don't pull in
-* `@cloudflare/workers-types` at runtime.
-*/
+ * The value types Workers KV can store / return. Mirrors Cloudflare's
+ * `KVNamespace` `get`/`put` body unions; declared here so the package stays
+ * runtime-agnostic and the `*Like` interfaces don't pull in
+ * `@cloudflare/workers-types` at runtime.
+ */
 type KvValue = ReadableStream | ArrayBuffer | ArrayBufferView | string;
 /** How a raw KV read should decode the stored value. Mirrors KV's `type` option. */
 type KvValueType = "text" | "json" | "arrayBuffer" | "stream";
 /**
-* Per-read options forwarded to the binding. `cacheTtl` is KV's edge-cache TTL
-* (seconds, min 60); `type` selects the decode mode for {@link Kv.getRaw}.
-*/
+ * Per-read options forwarded to the binding. `cacheTtl` is KV's edge-cache TTL
+ * (seconds, min 60); `type` selects the decode mode for {@link Kv.getRaw}.
+ */
 interface KvGetOptions {
   /** KV edge-cache TTL in seconds (minimum 60). Forwarded verbatim. */
   cacheTtl?: number;
@@ -18,23 +18,23 @@ interface KvGetOptions {
   type?: KvValueType;
 }
 /**
-* Minimal projection of Cloudflare's `KVNamespace`. Declared structurally so
-* unit tests can pass a plain `Map`-backed double; the real binding satisfies
-* the same shape. Mirrors `R2BucketLike` in `@lunora/storage`.
-*/
+ * Minimal projection of Cloudflare's `KVNamespace`. Declared structurally so
+ * unit tests can pass a plain `Map`-backed double; the real binding satisfies
+ * the same shape. Mirrors `R2BucketLike` in `@lunora/storage`.
+ */
 interface KVNamespaceLike {
   /** Delete a key. No-op if the key is absent. */
   delete: (key: string) => Promise<void>;
   /**
-  * Read a value. The real binding overloads on `options.type`; declared here
-  * as the broad union so a structural double need only return the value (or
-  * `null` when absent).
-  */
+   * Read a value. The real binding overloads on `options.type`; declared here
+   * as the broad union so a structural double need only return the value (or
+   * `null` when absent).
+   */
   get: (key: string, options?: KvGetOptions | KvValueType) => Promise<unknown>;
   /**
-  * Read a value together with its associated metadata. Returns
-  * `{ value: null, metadata: null }` when the key is absent.
-  */
+   * Read a value together with its associated metadata. Returns
+   * `{ value: null, metadata: null }` when the key is absent.
+   */
   getWithMetadata: (key: string, options?: KvGetOptions | KvValueType) => Promise<{
     metadata: unknown;
     value: unknown;
@@ -80,11 +80,11 @@ type KvNamespaceListResult<Metadata = unknown> = {
 /** Construction options for the `createKv` factory. */
 interface LunoraKvOptions {
   /**
-  * Optional per-instance key prefix applied to every operation (get/put/
-  * delete/list). Use for multi-tenant key namespacing — equivalent to
-  * calling the `scopeKey` helper on every key. Combined via `scopeKey`, so a
-  * `..` or NUL in the prefix is rejected.
-  */
+   * Optional per-instance key prefix applied to every operation (get/put/
+   * delete/list). Use for multi-tenant key namespacing — equivalent to
+   * calling the `scopeKey` helper on every key. Combined via `scopeKey`, so a
+   * `..` or NUL in the prefix is rejected.
+   */
   keyPrefix?: string;
   /** The bound KV namespace (`env.&lt;BINDING>`). */
   namespace: KVNamespaceLike;
@@ -98,9 +98,9 @@ interface KvPutOptions {
   /** Arbitrary metadata stored alongside the value (returned by `getWithMetadata`/`list`). */
   metadata?: unknown;
   /**
-  * When true, write `value` to KV verbatim (no `JSON.stringify`). `value`
-  * must already be a KV-writable type (string/ArrayBuffer/stream).
-  */
+   * When true, write `value` to KV verbatim (no `JSON.stringify`). `value`
+   * must already be a KV-writable type (string/ArrayBuffer/stream).
+   */
   raw?: boolean;
 }
 /** Options for {@link Kv.list}. */
@@ -117,9 +117,9 @@ interface KvListResult<Metadata = unknown> {
   /** Cursor for the next page; `undefined` when the listing is complete. */
   cursor?: string;
   /**
-  * The key names, with any instance `keyPrefix` stripped back off so callers
-  * see the same keys they wrote.
-  */
+   * The key names, with any instance `keyPrefix` stripped back off so callers
+   * see the same keys they wrote.
+   */
   keys: KvListKey<Metadata>[];
   /** True when this is the final page (no further `cursor`). */
   listComplete: boolean;
@@ -132,46 +132,140 @@ interface KvValueWithMetadata<Value, Metadata> {
   value: Value | null;
 }
 /**
-* The typed Workers KV client bound to `ctx.kv`. JSON-decodes/encodes by
-* default; a raw escape hatch ({@link Kv.getRaw} / `put(..., { raw: true })`)
-* handles text/binary/stream values.
-*/
+ * The typed Workers KV client bound to `ctx.kv`. JSON-decodes/encodes by
+ * default; a raw escape hatch ({@link Kv.getRaw} / `put(..., { raw: true })`)
+ * handles text/binary/stream values.
+ */
 interface Kv {
   /** Delete a key. No-op if absent. */
   delete: (key: string) => Promise<void>;
   /**
-  * Read a key and `JSON.parse` it into `T`. Returns `null` when the key is
-  * absent. Throws if the stored value isn't valid JSON — use
-  * {@link Kv.getRaw} for non-JSON values.
-  */
+   * Read a key and `JSON.parse` it into `T`. Returns `null` when the key is
+   * absent. Throws if the stored value isn't valid JSON — use
+   * {@link Kv.getRaw} for non-JSON values.
+   */
   get: <T = unknown>(key: string, options?: {
     cacheTtl?: number;
   }) => Promise<T | null>;
   /** Read a raw value with an explicit decode `type` (default `"text"`). Returns `null` when absent. */
   getRaw: <T = string>(key: string, options?: KvGetOptions) => Promise<T | null>;
   /**
-  * Read a key's JSON value together with its metadata. Returns
-  * `{ value: null, metadata: null }` when the key is absent.
-  */
+   * Read a key's JSON value together with its metadata. Returns
+   * `{ value: null, metadata: null }` when the key is absent.
+   */
   getWithMetadata: <T = unknown, M = unknown>(key: string, options?: {
     cacheTtl?: number;
   }) => Promise<KvValueWithMetadata<T, M>>;
   /** List keys (optionally `prefix`-filtered, paginated via `cursor`). */
   list: <M = unknown>(options?: KvListOptions) => Promise<KvListResult<M>>;
   /**
-  * Write `value` to `key`. JSON-stringifies `value` unless `options.raw` is
-  * set (in which case `value` must be a KV-writable type). Forwards
-  * `expirationTtl`/`expiration`/`metadata` to the binding.
-  */
+   * Write `value` to `key`. JSON-stringifies `value` unless `options.raw` is
+   * set (in which case `value` must be a KV-writable type). Forwards
+   * `expirationTtl`/`expiration`/`metadata` to the binding.
+   */
   put: <T = unknown>(key: string, value: T, options?: KvPutOptions) => Promise<void>;
 }
 /**
-* Compose a per-tenant key from a scope prefix and a caller-supplied key. Both
-* halves are validated — the prefix may not contain `..` or NUL either, and the
-* resulting key must stay under KV's length ceiling. Recommended for any
-* multi-tenant deployment so client-supplied keys can't address peer data.
-* Mirrors `scopeKey` from `@lunora/storage`.
-*/
+ * Compose a per-tenant key from a scope prefix and a caller-supplied key. Both
+ * halves are validated — the prefix may not contain `..` or NUL either, and the
+ * resulting key must stay under KV's length ceiling. Recommended for any
+ * multi-tenant deployment so client-supplied keys can't address peer data.
+ * Mirrors `scopeKey` from `@lunora/storage`.
+ */
 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 { createKv, scopeKey } from '../packem_shared/createKv-C8Iyu5hD.mjs';
+export { createKvIntrospector, createKvIntrospectorFromEnv } from '../packem_shared/createKvIntrospector-Byk4GfsY.mjs';

package/dist/packem_shared/{AnalyticsSqlError-CGTdsi4H.mjs → AnalyticsSqlError-C2nz3jpH.mjs}

@@ -1,10 +1,9 @@
+import { LunoraError } from '@lunora/errors';
+
 const SQL_API_BASE = "https://api.cloudflare.com/client/v4/accounts";
-class AnalyticsSqlError extends Error {
-  status;
+class AnalyticsSqlError extends LunoraError {
   constructor(status, body) {
-    super(`Analytics Engine SQL API returned ${String(status)}: ${body}`);
-    this.name = "AnalyticsSqlError";
-    this.status = status;
+    super("ANALYTICS_SQL_ERROR", `Analytics Engine SQL API returned ${String(status)}: ${body}`, { name: "AnalyticsSqlError", status });
   }
 }
 const createAnalyticsSqlClient = (config) => {

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

@@ -1,5 +1,6 @@
-import SelectBuilder from './SelectBuilder-BGXfCF0J.mjs';
-import { toText } from './Sql-CkDyJ_Sc.mjs';
+import { LunoraError } from '@lunora/errors';
+import SelectBuilder from './SelectBuilder-BOqJQHEv.mjs';
+import { ident, toText } from './Sql-B3zq2YGx.mjs';
 
 const API_BASE = "https://api.sql.cloudflarestorage.com/api/v1/accounts";
 const inferColumns = (rows) => {
@@ -10,12 +11,9 @@ const inferColumns = (rows) => {
     return { name };
   });
 };
-class R2SqlError extends Error {
-  status;
+class R2SqlError extends LunoraError {
   constructor(status, body) {
-    super(`R2 SQL query failed (${String(status)}): ${body}`);
-    this.name = "R2SqlError";
-    this.status = status;
+    super("R2_SQL_ERROR", `R2 SQL query failed (${String(status)}): ${body}`, { name: "R2SqlError", status });
   }
 }
 const createR2Sql = (config) => {
@@ -53,12 +51,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-BOqJQHEv.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-DZbQCxh1.mjs';
+import SetOperation from './SetOperation-DmPgUL8W.mjs';
+import { tableRef, toText, assertLimit, lit } from './Sql-B3zq2YGx.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) {
@@ -91,6 +91,7 @@ class SelectBuilder {
   }
   /** `LIMIT n` (R2 SQL: 1–10,000, default 500). */
   limit(n) {
+    assertLimit(n);
     this.limitValue = n;
     return this;
   }
@@ -156,7 +157,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-DmPgUL8W.mjs}

@@ -1,5 +1,5 @@
-import { renderOrderTerm } from './asc-C6Jbaa6R.mjs';
-import { lit } from './Sql-CkDyJ_Sc.mjs';
+import { renderOrderTerm } from './asc-DZbQCxh1.mjs';
+import { assertLimit, lit } from './Sql-B3zq2YGx.mjs';
 
 const renderMember = (query) => {
   const text = query.toSQL();
@@ -44,6 +44,7 @@ class SetOperation {
   }
   /** `LIMIT` applied to the combined result. */
   limit(n) {
+    assertLimit(n);
     this.limitValue = n;
     return this;
   }