ignotum 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,161 @@
+# Ignotum
+
+Ignotum is an opinionated TypeScript application cloud. Define a schema, queries, and mutations,
+then call them from the client with end-to-end types and realtime updates.
+
+The current release supports local development. Hosted infrastructure is not included yet.
+
+## Get started
+
+Ignotum requires Node.js 22.18 or newer.
+
+```sh
+npx ignotum new my-app
+cd my-app
+npx ignotum dev
+```
+
+Open <http://127.0.0.1:3210>. The generated project contains a schema, a query, a mutation, and a
+JSX client.
+
+## Follow the example app
+
+```text
+client/
+  App.tsx
+  styles.css
+server/
+  counter.ts
+  schema.ts
+shared/
+  utils.ts
+```
+
+Ignotum creates `_generated` beside them. Do not edit that directory by hand.
+
+### Define the data
+
+`server/schema.ts` declares a `counters` table with one numeric field:
+
+```ts
+import { defineSchema } from "ignotum/server";
+
+export default defineSchema(({ table, values }) => ({
+  counters: table({
+    value: values.number(),
+  }),
+}));
+```
+
+The schema supplies both runtime validation and TypeScript types. Ignotum also adds `id`,
+`createdAt`, and `updatedAt` to every stored document.
+
+The `shared/utils.ts` keeps the increment in one place that both the client and server
+can import:
+
+```ts
+export const counterIncrement = 1;
+```
+
+### Read and write from the server
+
+`server/counter.ts` defines the functions exposed to the client.
+
+```ts
+import { mutation, query, values } from "@/_generated/server.js";
+import { counterIncrement } from "@/shared/utils.js";
+
+export const get = query({
+  returns: values.number(),
+
+  handler: function* (ctx) {
+    const counters = yield* ctx.db.query("counters").collect();
+    return counters[0]?.value ?? 0;
+  },
+});
+
+export const increment = mutation({
+  handler: function* (ctx) {
+    const counters = yield* ctx.db.query("counters").collect();
+    const counter = counters[0];
+    const value = (counter?.value ?? 0) + counterIncrement;
+
+    if (counter === undefined) {
+      yield* ctx.db.insert("counters", { value });
+    } else {
+      yield* ctx.db.patch("counters", counter.id, { value });
+    }
+  },
+});
+```
+
+Server handlers are generator functions. If `function*` and `yield*` look scary, read `function*`
+as `async function` and `yield*` as `await`. That mental model is close enough when writing an
+Ignotum handler. Use `yield*` for database operations, then return plain values from queries. Query
+handlers can only read data. Mutation handlers can read and write, and Ignotum rolls back their
+writes if they fail.
+
+The file and export names form the generated API. The functions above become `api.counter.get`
+and `api.counter.increment`.
+
+### Call the functions from the client
+
+`client/App.tsx` uses the generated references to call the server functions.
+
+```tsx
+import { Result, useMutation, useQuery } from "ignotum/client";
+
+import { api } from "@/_generated/api.js";
+import { counterIncrement } from "@/shared/utils.js";
+
+export default function App() {
+  const count = useQuery(api.counter.get);
+  const increment = useMutation(api.counter.increment);
+
+  return (
+    <main class="mx-auto max-w-sm px-6 py-20 text-center">
+      <h1 class="text-2xl font-semibold">Counter</h1>
+      {Result.match(count, {
+        pending: () => <p class="mt-6">Loading...</p>,
+        value: (value) => (
+          <>
+            <p class="my-6 text-5xl tabular-nums">{value}</p>
+            <button
+              class="rounded bg-zinc-900 px-4 py-2 text-white"
+              type="button"
+              onClick={() => void increment()}
+            >
+              Increment by {counterIncrement}
+            </button>
+          </>
+        ),
+      })}
+    </main>
+  );
+}
+```
+
+`useQuery` starts with a pending result and subscribes to later values. `Result.match` makes the UI
+handle each query state. `useMutation` returns a typed function whose arguments come from the
+server definition.
+
+Open the app in two browser tabs and increment the counter in either one. Both tabs update because
+Ignotum refreshes active queries after a successful mutation.
+
+## Keep working
+
+The dev server watches the schema and server modules, regenerates bindings, and reloads the app.
+Run code generation separately before a typecheck when the dev server is not running:
+
+```sh
+npx ignotum codegen
+npx tsc --noEmit
+```
+
+Local data survives dev-server restarts. Stop the server before resetting it:
+
+```sh
+npx ignotum dev db reset
+```
+
+The package exports server APIs from `ignotum/server` and client APIs from `ignotum/client`.

package/dist/cli/bin.d.mts

@@ -0,0 +1 @@
+export {}