@codenotch/codenotch.cli 1.0.41 → 1.0.42

package/resources/docs/queries.md

@@ -0,0 +1,54 @@
+# CNQL queries
+
+The `.cnql` read queries a process runs through `ctx.query`, and what is still unsettled in their syntax.
+
+CNQL is an XML query language for reading data. A query lives in its own `.cnql` file,
+conventionally under `queries/`, and is run from a process:
+
+```ts
+const lists = await ctx.query<ITodoList>('queries/all-todolists.cnql')
+const todos = await ctx.query<ITodo>('queries/todos-of-list.cnql', { listId: input.listId })
+```
+
+The path is relative to the project root; the type parameter types the returned rows.
+
+## Structure
+
+```xml
+<CNQL xmlns="myservice" PageSize="100" PageIndex="0">
+    <TodoList Ref="results">
+        <Id />
+        <Name />
+        <CreatedAt />
+    </TodoList>
+</CNQL>
+```
+
+- The root is `<CNQL>`, its `xmlns` is the **service name** of the project (`serviceName` of
+  `manifest.json`), `PageSize`/`PageIndex` paginate the result.
+- The first child is the queried **table**, named as declared in its `defineEntity` (`TodoList`,
+  not `todolists`). `Ref` names the output.
+- Its children are the **columns** to select, PascalCase. `CreatedAt` is maintained by the
+  runtime and can be selected without being declared on the entity.
+
+Only reads: inserts, updates and deletes go through `ctx.tables` in a process.
+
+## What is not settled yet — keep the TODO policy
+
+The **filter syntax** (restricting rows, binding the parameters passed as the second argument of
+`ctx.query`) is not settled in the runtime yet. Generated projects mark the spot with an explicit
+comment instead of guessing:
+
+```xml
+<!-- TODO: filter on the 'listId' parameter passed by the process. The filtering syntax of CNQL is not settled yet. -->
+<CNQL xmlns="myservice" PageSize="100" PageIndex="0">
+    <Todo Ref="results">
+        <Id />
+        <Title />
+        <ListId />
+    </Todo>
+</CNQL>
+```
+
+Do the same: never invent a filter, join, ordering or grouping syntax. When a query needs one,
+write the unfiltered query, carry the `TODO` comment, and mention it to the user.

package/resources/docs/tables.md

@@ -0,0 +1,97 @@
+# Tables and documents
+
+How to declare the SQL tables and NoSQL documents of a project with `@codenotch/orm`, and how they become `db-schema.xml` and the typed `ctx.tables`.
+
+## Declaring a table
+
+A table is a `defineEntity({...})` declaration, conventionally one file per table under `tables/`:
+
+```ts
+import { defineEntity, type InferEntity, p } from '@codenotch/orm';
+
+export const TodoList = defineEntity({
+  name: 'TodoList',
+  properties: {
+    id: p.uuid().primary(),
+    name: p.string().notNull(),
+    // Deleting a list deletes its todos
+    todos: p.hasMany('Todo').linkBehaviour('Delete'),
+  },
+});
+
+export type ITodoList = InferEntity<typeof TodoList>;
+```
+
+Three conventions are load-bearing, the CLI warns and skips when they are broken:
+
+- the variable is **exported** and `name` is a **string literal** (a name built at runtime cannot
+  be discovered from the sources);
+- the row type is exported next to it: `export type ITodoList = InferEntity<typeof TodoList>` —
+  without it the table is left out of the typed `ctx.tables`;
+- table names are unique once pluralized (see collection names below).
+
+## Column builders
+
+Everything `p` exposes, with the aliases mapping to the same schema type:
+
+| Builder | Schema type |
+| --- | --- |
+| `p.string()` — accepts a length, e.g. `p.string(255)` | String |
+| `p.text()` | Text |
+| `p.email()` | Email |
+| `p.integer()` / `p.int()` | Integer |
+| `p.decimal()` / `p.float()` / `p.number()` | Decimal |
+| `p.boolean()` / `p.bool()` | Boolean |
+| `p.uuid()` / `p.guid()` | Guid |
+| `p.date()` | Date |
+| `p.datetime()` / `p.timestamp()` | DateTime |
+| `p.version()` | Version |
+| `p.enum()` | Enum |
+| `p.autoIncrement()` | AutoIncrement |
+| `p.belongsTo('Target')` | relation, holds the foreign key |
+| `p.hasOne('Target')` / `p.hasMany('Target')` | relation on the other side |
+
+A builder outside this list is reported as a warning and left out of the schema — it is never
+silently mapped to a guessed type.
+
+Modifiers, chained after the builder:
+
+| Modifier | Effect |
+| --- | --- |
+| `.primary()` | primary key (implies non-nullable) |
+| `.notNull()` / `.required()` | non-nullable |
+| `.unique()` | uniqueness constraint |
+| `.default(value)` | default value (a literal) |
+| `.linkBehaviour('Delete')` | on a relation: deleting the parent deletes the linked rows |
+
+A `hasMany`/`hasOne` finds its paired `belongsTo` on the target table automatically; declare the
+`belongsTo` side explicitly when the target has several relations to the same table.
+
+## Collection names — how `ctx.tables` is keyed
+
+A table is reachable in the processes under its lowercased, pluralized name: `TodoList` →
+`ctx.tables.todolists`, `Box` → `ctx.tables.boxes`, `Category` → `ctx.tables.categories`. Two
+tables mapping to the same collection name is a conflict: only the first one is kept, with a
+warning.
+
+## Documents
+
+A document is declared the same way with `defineDocument({...})` (conventionally under
+`documents/`), its type exported with `InferDocument`. Documents are keyed by their lowercased
+name, **not** pluralized, and typed as document-store handles rather than table handles.
+
+## Generation
+
+```sh
+cn generate dbcontext -f .
+```
+
+writes two files at the project root — both generated, never edit them:
+
+- `db-schema.xml` — the schema the runtime migrates the database from;
+- `db-schema.d.ts` — augments the `ProjectTables` and `ProjectDocs` interfaces of
+  `@codenotch/process` by declaration merging, so `ctx.tables.<collection>` autocompletes with
+  the row type of the table.
+
+Regenerate after every change to a `defineEntity`/`defineDocument` declaration. The project's
+`tsconfig.json` must keep `db-schema.d.ts` in its `include` for the merging to apply.