@lunora/server 1.0.0-alpha.16 → 1.0.0-alpha.18

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -99,6 +99,52 @@ The builder chain is `<builder>.input(validators).<kind>(handler)`, plus `.use(m
 
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/server)**.
 
+### Caching with Workers Cache
+
+Lunora supports Cloudflare Workers Cache for HTTP actions (`httpRoute`). RPC queries and mutations are `POST /_lunora/rpc` and are not cacheable at the edge by design.
+
+**Enable Workers Cache** in `wrangler.jsonc`:
+
+```jsonc
+{
+    "cache": { "enabled": true },
+}
+```
+
+The dev server and CLI automatically bump `compatibility_date` to the minimum required when cache is enabled — you do not need to set it manually.
+
+**Set cache headers declaratively** on an `httpRoute`:
+
+```ts
+import { httpRoute } from "./_generated/server";
+
+export const getProduct = httpRoute
+    .get("/api/products/:id")
+    .params({ id: v.string() })
+    .cacheControl("public, max-age=300, stale-while-revalidate=3600")
+    .cacheTag("products")
+    .handler(async ({ ctx, params }) => {
+        return { id: params.id, name: "Widget" };
+    });
+```
+
+**Purge cache by tag** from an action handler:
+
+```ts
+import { action } from "./_generated/server";
+
+export const refreshProducts = action.action(async ({ ctx }) => {
+    if (!ctx.cache) {
+        throw new Error("Workers Cache is not enabled in wrangler.jsonc");
+    }
+
+    await ctx.cache.purge({ tags: ["products"] });
+    return { ok: true };
+});
+```
+
+The `ctx.cache.purge` API accepts `{ tags?: string[]; purgeEverything?: boolean }`. Only action handlers expose `ctx.cache`; queries and mutations run inside the Durable Object and do not have access to the Worker-level cache binding.
+
 ## Related
 
 - [`@lunora/values`](https://www.npmjs.com/package/@lunora/values) — the `v.*` validators re-exported here.

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { Validator, Infer, ValidatorMap, InferValidatorMap, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
 import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
-export { type AnyApi, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
+export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
 import { LunoraError as LunoraError$1, LunoraErrorCode } from '@lunora/errors';
 export type { LunoraErrorCode } from '@lunora/errors';
 import { Context, Hono } from 'hono';
@@ -435,7 +435,7 @@ type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PU
 * `storage` surface — reach the data layer through `runQuery` / `runMutation` /
 * `runAction`, which forward to the owning shard.
 */
-type HttpActionCtx = Pick<ActionCtx, "auth" | "fetch" | "runAction" | "runMutation" | "runQuery">;
+type HttpActionCtx = Pick<ActionCtx, "auth" | "cache" | "fetch" | "runAction" | "runMutation" | "runQuery">;
 /** A raw handler wrapped by {@link httpAction}. Receives the raw request, returns the raw response. */
 type HttpActionHandler = (context: HttpActionCtx, request: Request) => Promise<Response> | Response;
 /**
@@ -519,6 +519,16 @@ interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params ex
 */
 interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator, Output = undefined> {
   body: <B extends ArgsValidator>(validators: B) => HttpRouteBuilder<SearchParams, B & Body, Params, Output>;
+  /**
+  * Attach a `Cache-Control` header to the response. Only meaningful when
+  * Workers Cache is enabled in `wrangler.jsonc` (`"cache": { "enabled": true }`).
+  */
+  cacheControl: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+  /**
+  * Attach a `Cache-Tag` header to the response for tag-based purging via
+  * `ctx.cache.purge({ tags: [...] })`.
+  */
+  cacheTag: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
   handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
   output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
   params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
@@ -533,6 +543,11 @@ interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends Args
   * handler's yielded type.
   */
   stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
+  /**
+  * Attach a `Vary` header to the response so Cloudflare stores separate
+  * cached variants per distinct value of the listed request headers.
+  */
+  vary: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
 }
 /** Opens a fresh {@link HttpRouteBuilder}. The `path` documents intent; hono owns the actual routing at mount. */
 type HttpRouteFactory = (path: string) => HttpRouteBuilder<EmptyArgs, EmptyArgs, EmptyArgs>;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Validator, Infer, ValidatorMap, InferValidatorMap, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
 import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.js";
-export { type AnyApi, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.js";
+export { type AnyApi, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.js";
 import { LunoraError as LunoraError$1, LunoraErrorCode } from '@lunora/errors';
 export type { LunoraErrorCode } from '@lunora/errors';
 import { Context, Hono } from 'hono';
@@ -435,7 +435,7 @@ type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PU
 * `storage` surface — reach the data layer through `runQuery` / `runMutation` /
 * `runAction`, which forward to the owning shard.
 */
-type HttpActionCtx = Pick<ActionCtx, "auth" | "fetch" | "runAction" | "runMutation" | "runQuery">;
+type HttpActionCtx = Pick<ActionCtx, "auth" | "cache" | "fetch" | "runAction" | "runMutation" | "runQuery">;
 /** A raw handler wrapped by {@link httpAction}. Receives the raw request, returns the raw response. */
 type HttpActionHandler = (context: HttpActionCtx, request: Request) => Promise<Response> | Response;
 /**
@@ -519,6 +519,16 @@ interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params ex
 */
 interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends ArgsValidator, Params extends ArgsValidator, Output = undefined> {
   body: <B extends ArgsValidator>(validators: B) => HttpRouteBuilder<SearchParams, B & Body, Params, Output>;
+  /**
+  * Attach a `Cache-Control` header to the response. Only meaningful when
+  * Workers Cache is enabled in `wrangler.jsonc` (`"cache": { "enabled": true }`).
+  */
+  cacheControl: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
+  /**
+  * Attach a `Cache-Tag` header to the response for tag-based purging via
+  * `ctx.cache.purge({ tags: [...] })`.
+  */
+  cacheTag: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
   handler: [Output] extends [undefined] ? <R>(handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Promise<R> | R) => LunoraRouteHandler : (handler: (options: HttpRouteHandlerOptions<SearchParams, Body, Params>) => Output | Promise<Output>) => LunoraRouteHandler;
   output: <V extends Validator>(validator: V) => HttpRouteBuilder<SearchParams, Body, Params, Infer<V>>;
   params: <P extends ArgsValidator>(validators: P) => HttpRouteBuilder<SearchParams, Body, P & Params, Output>;
@@ -533,6 +543,11 @@ interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends Args
   * handler's yielded type.
   */
   stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
+  /**
+  * Attach a `Vary` header to the response so Cloudflare stores separate
+  * cached variants per distinct value of the listed request headers.
+  */
+  vary: (value: string) => HttpRouteBuilder<SearchParams, Body, Params, Output>;
 }
 /** Opens a fresh {@link HttpRouteBuilder}. The `path` documents intent; hono owns the actual routing at mount. */
 type HttpRouteFactory = (path: string) => HttpRouteBuilder<EmptyArgs, EmptyArgs, EmptyArgs>;

package/dist/index.mjs

@@ -4,7 +4,7 @@ export { createSecrets } from './packem_shared/createSecrets-DwaR2rNG.mjs';
 export { LunoraEnvError, defineEnv, redactSecrets } from './packem_shared/LunoraEnvError-BGmd1Qs0.mjs';
 export { LunoraError } from './packem_shared/LunoraError-WbxmrpxR.mjs';
 export { bindOrm, bindTableFacade } from './packem_shared/bindOrm-CNXKgfUa.mjs';
-export { httpAction, httpRoute, httpRouter, isSafeHeaderValue, serveStorageObject } from './packem_shared/httpAction-B_16WzMO.mjs';
+export { httpAction, httpRoute, httpRouter, isSafeHeaderValue, serveStorageObject } from './packem_shared/httpAction-DCXoYPIk.mjs';
 export { defineIdentity } from './packem_shared/defineIdentity-DiX4zM9x.mjs';
 export { onConnect, onDisconnect } from './packem_shared/onConnect-CIPXKPyw.mjs';
 export { defineMigration } from './packem_shared/defineMigration-Hx01yIht.mjs';

package/dist/packem_shared/{httpAction-B_16WzMO.mjs → httpAction-DCXoYPIk.mjs}

@@ -110,7 +110,11 @@ const errorResponse = (error) => {
     return Response.json({ code: "BAD_REQUEST", error: error.message }, { status: 400 });
   }
   if (error instanceof LunoraError) {
-    return Response.json({ code: error.code, error: error.message }, { status: error.status });
+    const { body, redacted, status } = toErrorBody(error, { fallbackCode: "INTERNAL_SERVER_ERROR", redactedMessage: "Internal error" });
+    if (redacted) {
+      console.error("[lunora] http action error (redacted on the wire):", error);
+    }
+    return Response.json({ code: body.code, error: body.message }, { status });
   }
   throw error;
 };
@@ -122,7 +126,21 @@ const buildRouteHandler = (state, userHandler) => async (c) => {
     const body = Object.keys(state.body).length > 0 ? await parseBody(state.body, c) : {};
     const result = await userHandler({ body, ctx: context, params, searchParams });
     const payload = state.output ? applyOutput(state.output, result) : result;
-    return payload === void 0 ? new Response(null, { status: 204 }) : Response.json(payload);
+    const headers = {};
+    if (state.cacheControl) {
+      headers["cache-control"] = state.cacheControl;
+    }
+    if (state.cacheTag) {
+      headers["cache-tag"] = state.cacheTag;
+    }
+    if (state.vary) {
+      headers.vary = state.vary;
+    }
+    const hasCacheHeaders = Object.keys(headers).length > 0;
+    if (payload === void 0) {
+      return new Response(null, { headers: hasCacheHeaders ? headers : void 0, status: 204 });
+    }
+    return Response.json(payload, { headers: hasCacheHeaders ? headers : void 0 });
   } catch (error) {
     return errorResponse(error);
   }
@@ -198,25 +216,31 @@ const buildStreamHandler = (state, userHandler) => (
         }
       }
     });
-    return new Response(stream, {
-      headers: {
-        "cache-control": "no-cache, no-transform",
-        "content-type": "text/event-stream; charset=utf-8",
-        // Hint to proxies (including Cloudflare's own buffering layer)
-        // that this response must not be coalesced.
-        "x-accel-buffering": "no"
-      }
-    });
+    const headers = {
+      // SSE responses must stay uncacheable so proxies don't buffer or
+      // coalesce live frames. `cacheControl()` is intentionally ignored
+      // for stream() routes; `cacheTag`/`vary` are also omitted because
+      // they only make sense alongside a cacheable response.
+      "cache-control": "no-cache, no-transform",
+      "content-type": "text/event-stream; charset=utf-8",
+      // Hint to proxies (including Cloudflare's own buffering layer)
+      // that this response must not be coalesced.
+      "x-accel-buffering": "no"
+    };
+    return new Response(stream, { headers });
   }
 );
 const makeRouteBuilder = (state) => {
   return {
     body: (validators) => makeRouteBuilder({ ...state, body: { ...state.body, ...validators } }),
+    cacheControl: (value) => makeRouteBuilder({ ...state, cacheControl: value }),
+    cacheTag: (value) => makeRouteBuilder({ ...state, cacheTag: value }),
     handler: (userHandler) => buildRouteHandler(state, userHandler),
     output: (validator) => makeRouteBuilder({ ...state, output: validator }),
     params: (validators) => makeRouteBuilder({ ...state, params: { ...state.params, ...validators } }),
     searchParams: (validators) => makeRouteBuilder({ ...state, searchParams: { ...state.searchParams, ...validators } }),
-    stream: (userHandler) => buildStreamHandler(state, userHandler)
+    stream: (userHandler) => buildStreamHandler(state, userHandler),
+    vary: (value) => makeRouteBuilder({ ...state, vary: value })
   };
 };
 const makeRouteFactory = (method) => (path) => makeRouteBuilder({ body: {}, method, params: {}, path, searchParams: {} });

package/dist/types.d.mts

@@ -690,6 +690,21 @@ interface Workflows {
   get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
 }
 /**
+* Programmatic cache purge surface exposed on {@link ActionCtx}. Actions run
+* in the Worker (not the DO), so they can reach the Worker's `ctx.cache.purge`.
+* Queries and mutations do not expose this — they run inside the Durable Object.
+*/
+interface CachePurge {
+  /**
+  * Purge cached responses matching the given tags, or everything when
+  * `purgeEverything` is true. Only available in action handlers.
+  */
+  purge: (options: {
+    purgeEverything?: boolean;
+    tags?: string[];
+  }) => Promise<unknown>;
+}
+/**
 * Structural projection of workers-types' `SecretsStoreSecret` binding — the
 * per-secret `secrets_store_secrets[]` binding whose `.get()` resolves the
 * secret value (or throws if it does not exist). Mirrored structurally so the
@@ -1136,6 +1151,13 @@ interface MutationCtx {
 }
 interface ActionCtx {
   readonly auth: AuthState;
+  /**
+  * Programmatic Workers Cache purge; see {@link CachePurge}.
+  * **Action-only** — actions run in the Worker, which has a `cache` binding.
+  * Queries and mutations run inside the Durable Object and do not expose this.
+  * Optional at runtime because Workers Cache is only present when enabled.
+  */
+  readonly cache?: CachePurge;
   readonly db: DatabaseWriter;
   /**
   * The validated, typed environment. Populated only when the project declares
@@ -1178,4 +1200,4 @@ interface ActionCtx {
 */
 type AnyApi = Record<string, Record<string, RegisteredFunction<ArgsValidator, unknown, FunctionKind>>>;
 declare const anyApi: AnyApi;
-export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };

package/dist/types.d.ts

@@ -690,6 +690,21 @@ interface Workflows {
   get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
 }
 /**
+* Programmatic cache purge surface exposed on {@link ActionCtx}. Actions run
+* in the Worker (not the DO), so they can reach the Worker's `ctx.cache.purge`.
+* Queries and mutations do not expose this — they run inside the Durable Object.
+*/
+interface CachePurge {
+  /**
+  * Purge cached responses matching the given tags, or everything when
+  * `purgeEverything` is true. Only available in action handlers.
+  */
+  purge: (options: {
+    purgeEverything?: boolean;
+    tags?: string[];
+  }) => Promise<unknown>;
+}
+/**
 * Structural projection of workers-types' `SecretsStoreSecret` binding — the
 * per-secret `secrets_store_secrets[]` binding whose `.get()` resolves the
 * secret value (or throws if it does not exist). Mirrored structurally so the
@@ -1136,6 +1151,13 @@ interface MutationCtx {
 }
 interface ActionCtx {
   readonly auth: AuthState;
+  /**
+  * Programmatic Workers Cache purge; see {@link CachePurge}.
+  * **Action-only** — actions run in the Worker, which has a `cache` binding.
+  * Queries and mutations run inside the Durable Object and do not expose this.
+  * Optional at runtime because Workers Cache is only present when enabled.
+  */
+  readonly cache?: CachePurge;
   readonly db: DatabaseWriter;
   /**
   * The validated, typed environment. Populated only when the project declares
@@ -1178,4 +1200,4 @@ interface ActionCtx {
 */
 type AnyApi = Record<string, Record<string, RegisteredFunction<ArgsValidator, unknown, FunctionKind>>>;
 declare const anyApi: AnyApi;
-export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/server",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.18",
   "description": "Server primitives for Lunora: defineSchema, defineTable, query, mutation, and action",
   "keywords": [
     "backend",
@@ -62,9 +62,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.1",
-    "@lunora/scheduler": "1.0.0-alpha.5",
-    "@lunora/values": "1.0.0-alpha.4",
+    "@lunora/errors": "1.0.0-alpha.2",
+    "@lunora/scheduler": "1.0.0-alpha.6",
+    "@lunora/values": "1.0.0-alpha.5",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.27"
   },