ignotum 0.0.7 → 0.0.9

package/README.md

@@ -1,13 +1,12 @@
 # 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.
+Ignotum is an opinionated TypeScript application cloud built around a schema, server queries and mutations,
+and a browser client. Generated references carry function argument, result, and error types from
+the server to the client.
 
-The current release supports local development and hosted deployment.
+The package requires Node.js 22.18 or newer.
 
-## Get started
-
-Ignotum requires Node.js 22.18 or newer.
+## Create an app
 
 ```sh
 npx ignotum new my-app
@@ -15,10 +14,7 @@ cd my-app
 npx ignotum dev
 ```
 
-Open <http://127.0.0.1:3210>. The generated app contains a schema, a query, a mutation, and a
-JSX client.
-
-## Follow the example app
+Open `http://127.0.0.1:3210`. The generated counter app has this source layout:
 
 ```text
 client/
@@ -31,108 +27,87 @@ shared/
   utils.ts
 ```
 
-Ignotum creates `_generated` beside them. Do not edit that directory by hand.
+Ignotum writes generated bindings to `_generated`. Read those files when investigating a type, but
+do not edit them.
 
-### Define the data
+## Define the schema
 
-`server/schema.ts` declares a `counters` table with one numeric field:
+`server/schema.ts` names the tables and validates their stored fields:
 
 ```ts
 import { defineSchema } from "ignotum/server";
 
 export default defineSchema(({ table, values }) => ({
-  counters: table({
-    value: values.number(),
-  }),
+  todos: table({
+    text: values.string(),
+    completed: values.boolean(),
+  }).index("by_completed", ["completed"]),
 }));
 ```
 
-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:
+Every document also has an `id`, `createdAt`, and `updatedAt`. IDs are typed by table, so an ID for
+one table cannot be passed where another table's ID is required.
 
-```ts
-export const counterIncrement = 1;
-```
+## Define functions
 
-### Read and write from the server
-
-`server/counter.ts` defines the functions exposed to the client.
+Put function modules directly inside `server`. The file and export names form the generated client
+address. This example exports `api.todos.list` and `api.todos.create`:
 
 ```ts
 import { mutation, query, values } from "@/_generated/server.js";
-import { counterIncrement } from "@/shared/utils.js";
-
-export const get = query({
-  returns: values.number(),
 
+export const list = query({
+  returns: values.array(values.doc("todos")),
   handler: function* (ctx) {
-    const counters = yield* ctx.db.query("counters").collect();
-    return counters[0]?.value ?? 0;
+    return yield* ctx.db.query("todos").collect();
   },
 });
 
-export const increment = mutation({
-  returns: values.number(),
-
-  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 });
-    }
-
-    return value;
+export const create = mutation({
+  args: { text: values.string() },
+  returns: values.id("todos"),
+  handler: function* (ctx, args) {
+    return yield* ctx.db.insert("todos", {
+      text: args.text,
+      completed: false,
+    });
   },
 });
 ```
 
-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.
+Handlers are generator functions. Use `yield*` for database operations and `return` for the public
+result. Queries can read. Mutations can read and write, and their writes commit together only when
+the function succeeds. Arguments, returned values, and declared application errors are checked at
+runtime as well as in TypeScript.
 
-The file and export names form the generated API. The functions above become `api.counter.get`
-and `api.counter.increment`.
+## Build the client
 
-### Call the functions from the client
-
-`client/index.tsx` defines the app title and uses the generated references to call the server
-functions.
+`client/index.tsx` default-exports one `app` definition. Use generated references with the query and
+mutation hooks:
 
 ```tsx
 import { app, Result, useMutation, useQuery } from "ignotum/client";
 
 import { api } from "@/_generated/api.js";
-import { counterIncrement } from "@/shared/utils.js";
 
 function App() {
-  const count = useQuery(api.counter.get);
-  const increment = useMutation(api.counter.increment);
+  const todos = useQuery(api.todos.list);
+  const create = useMutation(api.todos.create);
 
   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 class="mx-auto max-w-xl p-8">
+      <button type="button" onClick={() => void create({ text: "New todo" })}>
+        Add todo
+      </button>
+
+      {Result.match(todos, {
+        pending: () => <p>Loading...</p>,
+        value: (items) => (
+          <ul>
+            {items.map((todo) => (
+              <li key={todo.id}>{todo.text}</li>
+            ))}
+          </ul>
         ),
       })}
     </main>
@@ -140,41 +115,54 @@ function App() {
 }
 
 export default app({
-  title: "Counter",
+  title: "Todos",
   component: App,
 });
 ```
 
-`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.
+`useQuery` subscribes while the component uses the result. It starts as `Pending` and then contains
+a value or declared application error. `useMutation` returns a stable typed function. Its promise
+settles after the mutation result arrives; affected queries may refresh afterward.
 
-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.
+Import UI components, hooks, and types from `ignotum/client`. Tailwind classes work without an app
+configuration file. Import any custom CSS from client code. An optional `client/icon.svg` becomes
+the favicon. Supported files in a top-level `public` directory retain their URL paths.
 
-Ignotum loads Tailwind CSS automatically. Custom CSS files are ordinary client modules and can use
-any filename when imported from app code.
+## Commands
 
-The optional `client/icon.svg` file becomes the favicon automatically. If it is absent, Ignotum
-does not add a favicon link.
+| Command                           | Purpose                                                            |
+| --------------------------------- | ------------------------------------------------------------------ |
+| `npx ignotum new <directory>`     | Create an app, optionally initialize Git, and install dependencies |
+| `npx ignotum install`             | Install with pnpm when available, otherwise npm                    |
+| `npx ignotum codegen`             | Regenerate `_generated` without starting the dev server            |
+| `npx ignotum dev`                 | Run the local app and watch client, schema, and function changes   |
+| `npx ignotum dev db reset`        | Delete local app data while the dev server is stopped              |
+| `npx ignotum auth login`          | Sign in to Ignotum with GitHub                                     |
+| `npx ignotum auth logout`         | Revoke and remove the saved login                                  |
+| `npx ignotum auth status`         | Show the current account and team                                  |
+| `npx ignotum deploy --app <slug>` | Link the app on its first deployment, then build and activate it   |
 
-Optional files in a top-level `public` directory keep their relative paths as public URLs. Ignotum
-accepts AVIF, GIF, ICO, JPEG, PNG, WebP, and PDF files there; `client/public` is not supported.
+Run `npx ignotum auth login` before the first deployment. The CLI stores the login outside the app
+directory. After the first deployment, it records the app link in `.ignotum/app.json`; later
+deployments do not need `--app`.
 
-## Keep working
+## Package entry points
 
-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:
+Application code uses two entry points:
 
-```sh
-npx ignotum codegen
-npx tsc --noEmit
-```
+- `ignotum/server` exports `defineSchema`, the server form of `Result`, and schema authoring types.
+- `ignotum/client` exports `app`, query and mutation hooks, `Query.skip`, client-side result
+  matching, application file URLs, and the supported UI APIs and types.
 
-Local data survives dev-server restarts. Stop the server before resetting it:
+Generated files provide schema-bound server builders and function references. Imports from
+`@/_generated/server.js` belong in server code. Imports from `@/_generated/api.js` belong in client
+code. Shared modules may be imported through `@/shared`.
 
-```sh
-npx ignotum dev db reset
-```
+## Current scope
+
+Ignotum currently supports schema-defined data, queries, mutations, live query results, application
+image files, local development, and hosted deployment. It does not provide authentication, custom
+HTTP endpoints, actions, scheduled jobs, or workflows.
 
-The package exports server APIs from `ignotum/server` and client APIs from `ignotum/client`.
+See the [Ignotum documentation](https://docs.ignotum.cloud) for validators, indexes, pagination,
+errors, consistency guarantees, hosted limits, and deployment behavior.