okengine 0.18.5 → 0.19.1

package/site/content/docs/elements/store/index.mdx

@@ -0,0 +1,313 @@
+---
+title: "Overview"
+description: "Data at rest — SQL, KV, files, and search indexes through one typed fx.store handle."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+Store is how your backend **holds data at rest**. Declare a facet once (`store.sql`, `store.kv`, `store.files`, `store.index`), then read and write through `fx.store(decl)` inside Flows.
+
+For developers persisting domain data on okengine — one handle shape, drivers swapped by environment.
+
+<Callout title="The one rule">
+  World access goes through `fx.store(decl)`. Drivers are **protocol-named** in `oke.config.ts`
+  (`postgres`, `redis`, `s3` — never vendors). Application code never imports a driver client
+  directly.
+</Callout>
+
+<StoreFacets />
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare a SQL store
+
+```typescript title="src/db/schema.decl.ts"
+import { store, field } from "okengine";
+
+export const notes = store.schema.table("notes", {
+  id: field.id().primaryKey(),
+  title: field.text().notNull(),
+  createdAt: field.timestamp().notNull().now(),
+});
+
+export const db = store.sql("app", { schema: { notes } });
+```
+
+</Step>
+
+<Step>
+### Read and write in a Flow
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { db, notes } from "@/schema";
+
+export const create = on(
+  http.post({
+    in: z.object({ title: z.string().min(1) }),
+  }),
+  flow({
+    do: async ({ title }, fx) => {
+      const id = fx.id();
+      await fx.store(db).insert(notes).values({ id, title });
+      return fx.json.create({ id, title });
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Call the endpoint
+
+```bash
+curl -X POST http://localhost:6530/notes \
+  -H "content-type: application/json" \
+  -d '{"title":"Ship notes"}'
+```
+
+Response:
+
+```json
+{
+  "data": { "id": "…", "title": "Ship notes" },
+  "error": null
+}
+```
+
+</Step>
+
+</Steps>
+
+<Callout title="Effects are inferred">
+  Every `fx.store` touch is recorded on the Flow as `reads` / `writes` (`sql:app`, `kv:sessions`,
+  `files:uploads`, …). That powers the Manifest, Console, cache invalidation, and least privilege —
+  no hand-written effect lists.
+</Callout>
+
+## Progressive Patterns
+
+Same `fx.store(decl)` from a row insert to cache, blobs, and hybrid search:
+
+<Tabs items={["SQL", "KV", "Files", "Search"]}>
+
+<Tab value="SQL">
+
+Declare tables with `store.schema.table` + `field.*`, then use the session handle:
+
+```typescript title="src/flows/notes/[id]/get.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { eq } from "drizzle-orm";
+import { db, notes } from "@/schema";
+
+export const get = on(
+  http.get({
+    in: z.object({ id: z.string() }),
+    errors: { NotFound: z.object({ id: z.string() }) },
+  }),
+  flow({
+    do: async ({ id }, fx) => {
+      const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
+      if (!note) return fx.fail("NotFound", { id });
+      return note;
+    },
+  }),
+);
+```
+
+Prefer [`store.resource`](/docs/elements/store/sql#resources) when you want five CRUD Flows in one factory.
+
+</Tab>
+
+<Tab value="KV">
+
+Pass the **declaration** into `fx.store` — there is no `fx.store.kv` namespace. TTL is a duration string:
+
+```typescript title="src/flows/sessions/put.ts"
+import { call } from "okengine";
+import { z } from "zod";
+import { sessions } from "@/core";
+
+export const putSession = call("sessions.put", {
+  in: z.object({ token: z.string(), userId: z.string() }),
+  do: async ({ token, userId }, fx) => {
+    await fx.store(sessions).set(`session:${token}`, userId, "1h");
+    return { ok: true };
+  },
+});
+```
+
+```typescript title="src/core.ts"
+import { store } from "okengine";
+
+export const sessions = store.kv("sessions");
+```
+
+</Tab>
+
+<Tab value="Files">
+
+Bucket I/O is `put` / `get` / `delete` / `list`. Images use `putImage` or the chainable `image(…)` pipeline:
+
+```typescript title="src/flows/avatars/create.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { uploads } from "@/core";
+
+export const create = on(
+  http.post({
+    in: z.object({ bytes: z.string() }),
+  }),
+  flow({
+    do: async ({ bytes }, fx) => {
+      const key = `avatars/${fx.id()}.png`;
+      const data = Uint8Array.from(atob(bytes), (c) => c.charCodeAt(0));
+      await fx.store(uploads).put(key, data);
+      return { key };
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Search">
+
+Mark text with `.searchable()` for BM25; chain `.embed()` only when you want semantic LSH:
+
+```typescript
+const { data, meta } = await fx.store(db).search(articles, {
+  query: "refund policy",
+  limit: 20,
+});
+```
+
+Full surface: [Search](/docs/elements/store/search).
+
+</Tab>
+
+</Tabs>
+
+## Facet Reference
+
+| Facet | Declare                    | `fx.store` handle                                        | Resource ref | Default drivers (dev / test / prod)   |
+| ----- | -------------------------- | -------------------------------------------------------- | ------------ | ------------------------------------- |
+| SQL   | `store.sql(name, opts?)`   | select / insert / update / page / search / …             | `sql:name`   | `postgres` / `pglite` / `postgres`    |
+| KV    | `store.kv(name, opts?)`    | `get` · `set` · `delete` · `list` · `ttlMs`              | `kv:name`    | `redis` / `memory` / `redis`          |
+| Files | `store.files(name, opts?)` | `put` · `get` · `delete` · `list` · `image` · `putImage` | `files:name` | `s3` / `memory` / `s3`                |
+| Index | `store.index(name, opts?)` | vector or Meilisearch (by `driverId`)                    | `index:name` | pin explicitly — no three-env default |
+
+Built-in hybrid search (`fx.store(db).search`) lives on the **SQL** handle — see [Search](/docs/elements/store/search). `store.index` is the optional external engine facet.
+
+## Per-environment drivers
+
+Standard starters inherit `DRIVER_DEFAULTS`. Pin only when you diverge; vendor choice lives under `images`, not driver ids:
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    // omit store.* to use defaults — pin only overrides
+  },
+  images: {
+    store: {
+      sql: "postgres:18-alpine",
+      kv: "redis:8-alpine",
+      files: "rustfs/rustfs:1.0.0-rc.5",
+    },
+  },
+});
+```
+
+| Facet   | Protocol ids                                    | Best for                                   |
+| ------- | ----------------------------------------------- | ------------------------------------------ |
+| `sql`   | `postgres` · `pglite` · `memory`                | Domain tables, RLS, live queries, BM25     |
+| `kv`    | `redis` · `memory` (+ durable SQL via `oke_kv`) | Sessions, caches, short-lived locks        |
+| `files` | `s3` · `fs` · `memory`                          | Uploads, exports, image variants           |
+| `index` | `memory` · `pgvector` · `meilisearch`           | Hosted FTS / ANN outside the primary table |
+
+## The Capabilities of Store
+
+<Cards>
+  <Card
+    title="SQL"
+    description="Schema tables, field tags, store.resource CRUD, RLS, and list grammar."
+    href="/docs/elements/store/sql"
+  />
+  <Card
+    title="KV"
+    description="Namespaced get/set with duration TTL — redis honors it; memory ignores it."
+    href="/docs/elements/store/kv"
+  />
+  <Card
+    title="Files"
+    description="Object buckets, putImage variants, and chainable Bun.Image transforms."
+    href="/docs/elements/store/files"
+  />
+  <Card
+    title="Search"
+    description="Built-in BM25 ± LSH on SQL columns, plus optional store.index engines."
+    href="/docs/elements/store/search"
+  />
+</Cards>
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="No sql/kv/files/index driver configured">
+  Boot needs a driver for that facet. Check `drivers.store.*` (or rely on `DRIVER_DEFAULTS`) and
+  that Compose / env URLs match the protocol.
+</Accordion>
+
+<Accordion title="Unknown store ref / Unknown kv ref">
+  `fx.store` received a declaration that was never registered — import the module that calls
+  `store.sql` / `store.kv` / … before the Flow runs (starters load `@/core`).
+</Accordion>
+
+<Accordion title='fx.store("sql:…"): no store runtime'>
+  The app has not booted a store runtime. Run through `oke` / `oke dev` so drivers bind; do not call
+  `fx.store` outside a Flow invoke.
+</Accordion>
+
+<Accordion title="OKE1110 — domain table not found">
+  Cause: `domain table not found — migrations have not been applied.` Run `oke db push` (dev) or
+  `oke db migrate` against that environment.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [SQL](/docs/elements/store/sql) — `store.schema.table`, `store.resource`, RLS
+- [HTTP · Resources](/docs/elements/flow/http#resources) — mount CRUD + live
+- [fx](/docs/reference/fx) — `fx.store`, `fx.json.*`
+- [Configuration](/docs/reference/configuration) — `drivers.store.*`
+- [Errors](/docs/reference/errors) — OKE1110 and friends
+
+## Next
+
+<Cards>
+  <Card
+    title="SQL"
+    description="Design tables, classify columns, and mount store.resource."
+    href="/docs/elements/store/sql"
+  />
+  <Card
+    title="Clock"
+    description="Schedules, intervals, and durable sleep."
+    href="/docs/elements/clock"
+  />
+  <Card
+    title="HTTP"
+    description="REST verbs, CRUD mounts, and live SSE on Flow."
+    href="/docs/elements/flow/http"
+  />
+</Cards>