@lunora/server 1.0.0-alpha.2 → 1.0.0-alpha.20

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

@@ -91,10 +91,60 @@ export const send = mutation
 
 The builder chain is `<builder>.input(validators).<kind>(handler)`, plus `.use(middleware)` and `.output(validator)`. `internalQuery` / `internalMutation` / `internalAction` are the same builders but kept off the public `api`. Run `lunora codegen` (or the Vite plugin) to (re)generate `_generated/` after a schema change.
 
-> **Determinism:** `query` and `mutation` handlers must be deterministic — they may be re-run on OCC retry or subscription re-evaluation. Compute time, randomness, and network results in an `action` (e.g. `Date.now()`, `crypto.randomUUID()`, `fetch`) and pass them into the mutation as arguments.
+> **Determinism:** `query` and `mutation` handlers must be deterministic — they may be re-run on OCC retry or subscription re-evaluation. Read the current time from **`ctx.now`** (epoch ms, captured once per execution — also on `ActionCtx`) instead of `Date.now()`; compute randomness and network results in an `action` (`crypto.randomUUID()`, `fetch`) and pass them into the mutation as arguments. The `nondeterministic_query_mutation` advisor flags `Date.now()`/`Math.random()`/`fetch` in query/mutation handlers.
+
+### Local-first sync engine
+
+`defineShape` declares a **partial replication shape** (a named table view with a server-resolved `where` predicate, AND-composed with RLS) and `defineMutator` declares a **custom mutator** (an authoritative `server` impl plus an optional optimistic `client` twin). Both are discovered by codegen and drive the [local-first sync engine](https://lunora.sh/docs/concepts/local-first) — clients subscribe to shapes over the poke diff protocol and push optimistic writes rebased over the server's authoritative result. The client-side runtime lives in [`@lunora/db`](https://www.npmjs.com/package/@lunora/db).
 
 > 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.