@antelopejs/interface-database-decorators 0.1.11 → 0.2.0

package/docs/2.table-definitions.md

@@ -1,10 +1,14 @@
-# Table Definitions
+---
+title: Table definitions
+description: Reference for the Table class and the Field, Index, Relation, RegisterTable, and Fixture decorators, RegisterSchema, and Table.table.
+mode: reference
+---
 
-The Database Decorators package provides a class-based approach to defining database tables. You extend the `Table` base class, declare each field with TypeScript's `declare` keyword and the `@Field` decorator, and use further decorators to configure indexes, relations, and initial data.
+A table is a class that extends `Table`. Each field is a property declared with TypeScript's `declare` keyword and the `@Field` decorator. Further decorators add indexes, relations, and initial data.
 
-## The Table Class
+## The `Table` class
 
-The `Table` class serves as the base class for all table definitions. Every table automatically includes an `_id` field as the primary key.
+`Table` is the base class of every table definition. It declares `_id: string`, the primary key of every table.
 
 ```typescript
 import { Table, Field } from "@antelopejs/interface-database-decorators";
@@ -18,9 +22,9 @@ class User extends Table {
 }
 ```
 
-### Extend with Modifiers
+### Extend with modifiers
 
-The `Table.with()` static method incorporates modifier mixins into the table class, adding capabilities like encryption, hashing, or localization:
+The static `Table.with()` method returns a subclass of the table class that holds the mixin methods of the modifiers it receives, such as encryption, hashing, or localization:
 
 ```typescript
 import {
@@ -45,11 +49,11 @@ class SensitiveData extends Table.with(EncryptionModifier) {
 }
 ```
 
-Provide a high-entropy key through your secret manager; do not use a default key. See [Table Modifiers](./3.table-modifiers.md#encryptionmodifier) for key format and date precision constraints.
+Provide a high-entropy key through your secret manager, and never a default key. See [Table modifiers](./3.table-modifiers.md#encryptionmodifier) for the key format and the date precision limit.
 
-## The Index Decorator
+## The `Index` decorator
 
-The `Index` decorator marks a field as a database index. Indexed fields enable efficient lookups through `getAll()` and `between()` on the underlying AQL table.
+The `Index` decorator marks a field as a database index. An indexed field serves lookups through `getAll()` and `between()` on the AQL table, and through the model's `getBy()`. `@Index` on a symbol-keyed property throws, because a database index names a field.
 
 ```typescript
 import { Table, Field, Index } from "@antelopejs/interface-database-decorators";
@@ -72,13 +76,15 @@ class User extends Table {
 | `crossInstance` | `boolean` | Also keep the index fast for queries that run across all instances. |
 | `unique`        | `boolean` | Refuse two rows of the instance with the same key.                  |
 
-### Cross-Instance Indexes
+### Cross-instance indexes
 
-Every index is scoped to the schema instance, so queries on a single instance always use it. Set `crossInstance: true` when the index is also queried across all instances (queries on the `CROSS_INSTANCE` instance), so the database driver maintains an additional index for those queries.
+Every index is scoped to the schema instance. Set `crossInstance: true` when queries across all instances (on the `CROSS_INSTANCE` instance) also use the index. The database driver then maintains an additional index for those queries.
 
-The option never changes query results. Without it, cross-instance queries that name the index still return the same rows but run slower, and the driver logs a warning once per index. Leave it unset for indexes that are only queried within one instance, since each extra index costs storage and write time.
+The option never changes query results. Without it, a cross-instance query that names the index returns the same rows but runs slower, and the `@antelopejs/mongodb` and `@antelopejs/rethinkdb` drivers log a warning once per index. Leave it unset for an index that only queries within one instance use, because each extra index costs storage and write time.
 
 ```typescript
+import { Field, Index, Table } from "@antelopejs/interface-database-decorators";
+
 class User extends Table {
   @Index({ crossInstance: true })
   @Field("string")
@@ -88,11 +94,13 @@ class User extends Table {
 
 For a compound index, setting `crossInstance: true` on any field of the group applies it to the whole group.
 
-### Unique Indexes
+### Unique indexes
 
-Set `unique: true` to refuse a second row with the same key in one instance. The write that would store it throws `DuplicateKeyError` from `@antelopejs/interface-database`, naming the index and its fields; test it with `IsDuplicateKeyError`. Rows of different instances may share a key.
+Set `unique: true` to refuse a second row with the same key in one instance. The write that would store it throws `DuplicateKeyError` from `@antelopejs/interface-database`, which names the index and its fields. Test for it with `IsDuplicateKeyError`. Rows of different instances may share a key.
 
 ```typescript
+import { Field, Index, Table } from "@antelopejs/interface-database-decorators";
+
 class Template extends Table {
   @Index({ unique: true })
   @Field("string")
@@ -100,9 +108,9 @@ class Template extends Table {
 }
 ```
 
-For a compound index, setting `unique: true` on any field of the group makes the whole group's key unique. Not every database module can enforce unique secondary indexes: one that cannot refuses the schema rather than ignoring the option.
+For a compound index, setting `unique: true` on any field of the group makes the whole group's key unique. Not every database module can enforce a unique secondary index. A module that cannot, such as `@antelopejs/rethinkdb`, refuses the schema instead of ignoring the option.
 
-### Compound Indexes
+### Compound indexes
 
 Assign multiple fields to the same index group to create a compound index:
 
@@ -134,11 +142,11 @@ class UserActivity extends Table {
 }
 ```
 
-## The Field Decorator
+## The `Field` decorator
 
-`@Field(type)` declares the field type for a property. The type is forwarded verbatim into the `TableDefinition.fields` map handed to the adapter. It accepts the full `FieldType` union -- primitive tokens (`"string"`, `"number"`, ...), arrays, nested records, or an io-ts codec.
+`@Field(type)` declares the type of a property. The type goes unchanged into the `TableDefinition.fields` map that the database module receives. It accepts every member of the `FieldType` union, for example a string token such as `"string"` or `"number"`, an array, a nested record, or an io-ts codec.
 
-```typescript
+```typescript fragment
 import * as t from "io-ts";
 import {
   Table,
@@ -161,13 +169,13 @@ class Order extends Table {
 }
 ```
 
-Properties without `@Field` are omitted from `fields`. `@Field` stacks freely with `@Index`.
+Properties without `@Field` are left out of `fields`. `@Field` and `@Index` each write their own metadata, so they combine in either order.
 
-## The Relation Decorator
+## The `Relation` decorator
 
-The `Relation` decorator declares a link from a field to another table. It is **declarative metadata only**: database implementations do not enforce it (no foreign key constraint, no referential validation). Introspection tooling consumes it to expose the links between tables — for example to render schema diagrams or navigate related records.
+The `Relation` decorator declares a link from a field to another table. It is metadata only. Database modules do not enforce it, with no foreign key constraint and no check that the target exists. Introspection tools read it to show the links between tables, for example in a schema diagram or to navigate to related records.
 
-```typescript
+```typescript fragment
 import {
   Table,
   Field,
@@ -195,11 +203,11 @@ class Comment extends Table {
 | `toField` | `string`             | Target field name. Defaults to the target table's primary key.                   |
 | `many`    | `boolean`            | The decorated field holds multiple target keys (many targets per source record). |
 
-`@Relation` stacks freely with `@Field` and `@Index`.
+`@Relation` writes its own metadata, so it combines with `@Field` and `@Index` in any order.
 
-## The RegisterTable Decorator
+## The `RegisterTable` decorator
 
-The `RegisterTable` class decorator associates a table class with a specific table name and schema. This registration is used by `RegisterSchema` to build the schema definition automatically.
+The `RegisterTable` class decorator gives a table class its table name and its schema. `RegisterSchema` builds the schema definition from these registrations.
 
 ```typescript
 import {
@@ -222,9 +230,9 @@ class User extends Table {
 
 The first argument is the table name in the database, and the second is the schema name.
 
-## The Fixture Decorator
+## The `Fixture` decorator
 
-The `Fixture` decorator defines default data to insert when a table is first created. It receives a generator function that produces initial records.
+The `Fixture` decorator defines the rows to insert into an empty table. It receives a generator function that returns them.
 
 ```typescript
 import {
@@ -246,13 +254,21 @@ class UserRole extends Table {
 
 The generator function:
 
-- Receives the table class as its parameter.
-- Can return a single object, an array of objects, or a `Promise` resolving to either.
-- Runs only when the table is empty, preventing duplicate inserts on subsequent starts.
+- Receives the table class registered into the schema, which is the decorated class or a subclass of it.
+- Can return a single object, an array of objects, or a `Promise` of either.
+- Runs when `RegisterSchema` finds the table empty, so a later start inserts nothing again.
 
-### Async Generators
+Only a table registered with `@RegisterTable` gets its fixture, from `RegisterSchema`. Each row goes through the same conversion as a model insert, so modifiers and the `insert` event apply. A row without an `_id` gets `<table>:fixture:<position>`, so two processes that start on the same empty table write one row between them.
+
+### Async generators
+
+```typescript fragment
+import {
+  Field,
+  Fixture,
+  Table,
+} from "@antelopejs/interface-database-decorators";
 
-```typescript
 @Fixture(async () => {
   const defaults = await loadDefaultConfig();
   return defaults.map((cfg) => ({
@@ -268,7 +284,7 @@ class SystemConfig extends Table {
 
 ## Inheritance
 
-Tables support standard class inheritance. Define a base table with common fields and extend it for specific use cases:
+A table class can extend another table class. The subclass starts with a copy of its parent's table and schema names, fields, indexes, and fixture, so decorators on the subclass do not change the parent:
 
 ```typescript
 import {
@@ -312,11 +328,11 @@ class Post extends BaseEntity {
 }
 ```
 
-## Register a Schema
+## Register a schema
 
-The `RegisterSchema` function builds a `SchemaDefinition` from all tables registered for the given schema id (via `@RegisterTable`), constructs the `Schema` (which the adapter provisions), binds each table class to that `Schema` (see [Open a Table from its Class](#open-a-table-from-its-class)), then inserts any fixture data for tables that are empty.
+The `RegisterSchema` function builds a `SchemaDefinition` from every table that `@RegisterTable` registered for the schema ID. It constructs the `Schema`, which the database module provisions, and binds each table class to it (see [Open a table from its class](#open-a-table-from-its-class)). Then it inserts the fixtures of the tables that are empty.
 
-Call it in the module that declares the tables: the binding then follows that module's database, whichever module later uses the classes.
+Call it in the module that declares the tables. The binding then follows that module's database, whichever module later uses the classes.
 
 ```typescript
 import { RegisterSchema } from "@antelopejs/interface-database-decorators";
@@ -330,13 +346,19 @@ await RegisterSchema("myapp");
 | ---------- | -------- | ------------------------------------------------------------------ |
 | `schemaId` | `string` | Schema id matching the `@RegisterTable(_, schemaId)` declarations. |
 
-`RegisterSchema` returns `Promise<void>`.
+`RegisterSchema` returns `Promise<void>`. It throws `No tables registered for schema '<schemaId>'` when no class registers into the schema.
 
-## Open a Table from its Class
+## Open a table from its class
 
 `Table.table()` returns the AQL table a class describes, in the schema `RegisterSchema` bound it to:
 
-```typescript
+```typescript fragment
+import {
+  RegisterSchema,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
 @RegisterTable("users", "myapp")
 class User extends Table {
   declare name: string;
@@ -349,4 +371,4 @@ User.table("tenant-1"); // instance "tenant-1" (CROSS_INSTANCE is accepted too)
 User.table(db); // db.table("users") on a SchemaInstance you already hold
 ```
 
-When given a `SchemaInstance`, `table()` takes the table from it as is: pass an instance of the class's own schema. A class that no `RegisterSchema` call bound throws, naming the class.
+Given a `SchemaInstance`, `table()` takes the table from it as is, so pass an instance of the class's own schema. A class without `@RegisterTable` throws `<Class> has no table name`. A class that no `RegisterSchema` call bound, and whose schema name has no schema, throws `<Class> is not bound to a schema`.