@junejs/juno 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 June.build
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @junejs/juno
+
+June's ergonomic data layer — a typed table API over the pure `JuneDb` contract
+(`@junejs/core/resources`), so it runs over sqlite / D1 / Postgres alike. Juno
+depends only on `@junejs/core` (inward); `@junejs/core` never imports Juno.
+
+```ts
+import { juno } from "@junejs/juno";
+
+const db = juno(ctx.db); // ctx.db is the injected `db` resource
+await db.table("users").all();
+await db.table("users").findBy({ email: "ada@x.dev" });
+await db.table("users").insert({ name: "Ada" });
+await db.table("users").update({ id: 1 }, { name: "Ada Lovelace" });
+```
+
+## The magic is opt-in, not load-bearing
+
+Juno is the **default** that ships at Tier 3: every read calls `recordTableRead`
+and every write `recordTableWrite` (@junejs/core's public trace contract). That is
+what makes `cache()` auto-tag by table and a mutation **auto-invalidate** the
+cache (and push live RSC) with zero manual `revalidate()`.
+
+This is a property of emitting the trace signals, **not** of using Juno. The
+framework depends on the contract, never on Juno — so Prisma/Drizzle stay
+first-class (Tier 1 = bring your own, untouched; Tier 2 = your ORM over `ctx.db`;
+Tier 3 = the same magic via a thin shim). See `docs/data-layer-boundary.md`.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@junejs/juno",
+  "version": "0.0.2",
+  "description": "Juno — June's ergonomic data layer over the JuneDb contract. The default that ships with the agent-native magic (Tier 3).",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://june.build",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@junejs/core": "0.0.0"
+  },
+  "devDependencies": {
+    "@junejs/server": "0.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junebuild/june"
+  }
+}

package/src/batch.ts

@@ -0,0 +1,73 @@
+// Auto-batch — the flagship data demo (rebuild-plan Phase 5; the render-level
+// auto-batch / D1 8.8× number in bench/results.json). When many components each
+// ask for a row by key during ONE render pass, a DataLoader-style loader
+// coalesces them within a microtask tick into a SINGLE `where key in (...)`
+// query: N+1 → 1. Per-request so keys never leak across requests.
+
+import type { JuneDb } from "@junejs/core/resources";
+import { recordTableRead } from "@junejs/core/instrumentation";
+
+import type { Row } from "./index";
+
+export type Loader<K, V> = {
+  load(key: K): Promise<V | null>;
+};
+
+// Generic batched loader: `batchFn(keys)` runs once per tick with all pending
+// keys; `keyOf(row)` maps a result back to the key that requested it.
+export function createLoader<K, V>(
+  batchFn: (keys: K[]) => Promise<V[]>,
+  keyOf: (value: V) => K,
+): Loader<K, V> {
+  let queue: { key: K; resolve: (v: V | null) => void; reject: (e: unknown) => void }[] = [];
+  let scheduled = false;
+
+  function flush() {
+    const batch = queue;
+    queue = [];
+    scheduled = false;
+    // Dedupe keys so repeated asks for the same row cost nothing extra.
+    const keys = [...new Set(batch.map((b) => b.key))];
+    batchFn(keys).then(
+      (values) => {
+        const byKey = new Map(values.map((v) => [keyOf(v), v]));
+        for (const b of batch) b.resolve(byKey.get(b.key) ?? null);
+      },
+      (err) => {
+        for (const b of batch) b.reject(err);
+      },
+    );
+  }
+
+  return {
+    load(key: K) {
+      return new Promise<V | null>((resolve, reject) => {
+        queue.push({ key, resolve, reject });
+        if (!scheduled) {
+          scheduled = true;
+          queueMicrotask(flush);
+        }
+      });
+    },
+  };
+}
+
+// A by-key loader over a JuneDb table: `loader.load(id)` calls coalesce into one
+// `select * from <table> where <key> in (?, ?, ...)`. Build one per request.
+export function tableLoader<V extends Row = Row>(
+  db: JuneDb,
+  table: string,
+  key = "id",
+): Loader<string | number, V> {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`unsafe SQL identifier: ${table}.${key}`);
+  }
+  return createLoader<string | number, V>(
+    async (keys) => {
+      recordTableRead(table); // batched read still participates in cache auto-tagging
+      const placeholders = keys.map(() => "?").join(", ");
+      return db.query<V>(`select * from ${table} where ${key} in (${placeholders})`, keys);
+    },
+    (row) => (row as Row)[key] as string | number,
+  );
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+// Juno — June's ergonomic data layer. A typed table API over the @junejs/core
+// JuneDb contract (so it works over sqlite / D1 / Postgres alike), depending ONLY
+// on @junejs/core (inward; @junejs/core never imports Juno). docs/data-layer-boundary.md.
+//
+// THE MAGIC (Tier 3): every read calls recordTableRead, every write
+// recordTableWrite — @junejs/core's PUBLIC trace contract. That is what makes cache
+// auto-tag by table and a mutation auto-invalidate + push live RSC, with zero
+// manual revalidate(). Juno emits these natively; Drizzle/Prisma reach the same
+// tier with a thin shim. The framework depends on the trace contract, not on Juno.
+
+import type { JuneDb, RunResult } from "@junejs/core/resources";
+import { recordTableRead, recordTableWrite } from "@junejs/core/instrumentation";
+
+import { tableLoader, type Loader } from "./batch";
+
+export { createLoader, tableLoader, type Loader } from "./batch";
+
+export type Row = Record<string, unknown>;
+
+// Guard table/column names (identifiers can't be parameterized). Values always
+// go through bound `?` placeholders, so they are injection-safe by construction.
+function ident(name: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe SQL identifier: ${name}`);
+  return name;
+}
+
+export class Table<T extends Row = Row> {
+  constructor(
+    private readonly db: JuneDb,
+    private readonly name: string,
+  ) {}
+
+  async all(): Promise<T[]> {
+    recordTableRead(this.name); // auto-tag: a cache() around this gets table:<name>
+    return this.db.query<T>(`select * from ${ident(this.name)}`);
+  }
+
+  async findBy(where: Partial<T>): Promise<T | undefined> {
+    recordTableRead(this.name);
+    const keys = Object.keys(where).map(ident);
+    const clause = keys.length ? ` where ${keys.map((k) => `${k} = ?`).join(" and ")}` : "";
+    return this.db.get<T>(`select * from ${ident(this.name)}${clause} limit 1`, Object.values(where));
+  }
+
+  async insert(values: Partial<T>): Promise<RunResult> {
+    recordTableWrite(this.name); // auto-invalidate: invokeAction drops table:<name>
+    const cols = Object.keys(values).map(ident);
+    const placeholders = cols.map(() => "?").join(", ");
+    return this.db.run(
+      `insert into ${ident(this.name)} (${cols.join(", ")}) values (${placeholders})`,
+      Object.values(values),
+    );
+  }
+
+  async update(where: Partial<T>, values: Partial<T>): Promise<RunResult> {
+    recordTableWrite(this.name);
+    const set = Object.keys(values).map((k) => `${ident(k)} = ?`).join(", ");
+    const cond = Object.keys(where).map((k) => `${ident(k)} = ?`).join(" and ");
+    return this.db.run(
+      `update ${ident(this.name)} set ${set} where ${cond}`,
+      [...Object.values(values), ...Object.values(where)],
+    );
+  }
+
+  async delete(where: Partial<T>): Promise<RunResult> {
+    recordTableWrite(this.name);
+    const cond = Object.keys(where).map((k) => `${ident(k)} = ?`).join(" and ");
+    return this.db.run(`delete from ${ident(this.name)} where ${cond}`, Object.values(where));
+  }
+
+  // A per-request by-key loader: concurrent .load(key) calls during one render
+  // pass coalesce into a single `where key in (...)` query (N+1 → 1). Build one
+  // per request so keys never leak across requests.
+  loader(key = "id"): Loader<string | number, T> {
+    return tableLoader<T>(this.db, this.name, key);
+  }
+}
+
+export type Juno = {
+  table<T extends Row = Row>(name: string): Table<T>;
+  db: JuneDb;
+};
+
+// Wrap any JuneDb handle (ctx.db) in Juno's ergonomic surface.
+export function juno(db: JuneDb): Juno {
+  return {
+    db,
+    table<T extends Row = Row>(name: string) {
+      return new Table<T>(db, name);
+    },
+  };
+}