diff --git a/docs/2.table-definitions.md b/docs/2.table-definitions.md index a589be4..1cf4e8e 100644 --- a/docs/2.table-definitions.md +++ b/docs/2.table-definitions.md @@ -1,16 +1,19 @@ # Table Definitions -The Database Decorators package provides a class-based approach to defining database tables. You extend the `Table` base class, declare fields with TypeScript's `declare` keyword, and use decorators to configure indexes and initial data. +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. ## 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. ```typescript -import { Table } from "@antelopejs/interface-database-decorators"; +import { Table, Field } from "@antelopejs/interface-database-decorators"; class User extends Table { + @Field("string") declare name: string; + + @Field("string") declare email: string; } ``` @@ -20,12 +23,14 @@ class User extends Table { The `Table.with()` static method incorporates modifier mixins into the table class, adding capabilities like encryption, hashing, or localization: ```typescript -import { Table, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators"; +import { Table, Field, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators"; class SensitiveData extends Table.with(EncryptionModifier) { + @Field("string") declare publicContent: string; @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" }) + @Field("string") declare secureContent: string; } ``` @@ -37,12 +42,14 @@ For detailed information about modifiers, see [Table Modifiers](./3.table-modifi The `Index` decorator marks a field as a database index. Indexed fields enable efficient lookups through `getAll()` and `between()` on the underlying AQL table. ```typescript -import { Table, Index } from "@antelopejs/interface-database-decorators"; +import { Table, Field, Index } from "@antelopejs/interface-database-decorators"; class User extends Table { @Index() + @Field("string") declare email: string; + @Field("string") declare name: string; } ``` @@ -58,15 +65,24 @@ class User extends Table { Assign multiple fields to the same index group to create a compound index: ```typescript -import { Table, Index } from "@antelopejs/interface-database-decorators"; +import { Table, Field, Index, Relation } from "@antelopejs/interface-database-decorators"; + +class User extends Table { + @Field("string") + declare name: string; +} class UserActivity extends Table { @Index({ group: "user_action" }) + @Field("string") + @Relation({ to: () => User }) declare userId: string; @Index({ group: "user_action" }) + @Field("string") declare action: string; + @Field("date") declare timestamp: Date; } ``` @@ -129,13 +145,15 @@ class Comment extends Table { 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. ```typescript -import { Table, Index, RegisterTable } from "@antelopejs/interface-database-decorators"; +import { Table, Field, Index, RegisterTable } from "@antelopejs/interface-database-decorators"; @RegisterTable("users", "myapp") class User extends Table { @Index() + @Field("string") declare email: string; + @Field("string") declare name: string; } ``` @@ -147,7 +165,7 @@ The first argument is the table name in the database, and the second is the sche The `Fixture` decorator defines default data to insert when a table is first created. It receives a generator function that produces initial records. ```typescript -import { Table, Fixture } from "@antelopejs/interface-database-decorators"; +import { Table, Field, Fixture } from "@antelopejs/interface-database-decorators"; @Fixture(() => [ { _id: "admin", name: "Administrator" }, @@ -155,6 +173,7 @@ import { Table, Fixture } from "@antelopejs/interface-database-decorators"; { _id: "guest", name: "Guest" }, ]) class UserRole extends Table { + @Field("string") declare name: string; } ``` @@ -176,6 +195,7 @@ The generator function: })); }) class SystemConfig extends Table { + @Field("string") declare value: string; } ``` @@ -185,24 +205,38 @@ class SystemConfig extends Table { Tables support standard class inheritance. Define a base table with common fields and extend it for specific use cases: ```typescript +import { Table, Field, Index, Relation } from "@antelopejs/interface-database-decorators"; + class BaseEntity extends Table { + @Field("date") declare createdAt: Date; + + @Field("date") declare updatedAt: Date; } class User extends BaseEntity { @Index() + @Field("string") declare email: string; + @Field("string") declare firstName: string; + + @Field("string") declare lastName: string; } class Post extends BaseEntity { @Index() + @Field("string") + @Relation({ to: () => User }) declare authorId: string; + @Field("string") declare title: string; + + @Field("string") declare content: string; } ``` diff --git a/docs/3.table-modifiers.md b/docs/3.table-modifiers.md index b27009c..b412d54 100644 --- a/docs/3.table-modifiers.md +++ b/docs/3.table-modifiers.md @@ -9,7 +9,7 @@ Table modifiers transform field values as they are stored in and retrieved from The `EncryptionModifier` encrypts field values before storing them and decrypts them on retrieval. Both operations happen transparently. ```typescript -import { Table, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators"; +import { Table, Field, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators"; class UserCredentials extends Table.with(EncryptionModifier) { @Encrypted({ @@ -17,9 +17,11 @@ class UserCredentials extends Table.with(EncryptionModifier) { algorithm: "aes-256-gcm", ivSize: 16, }) + @Field("string") declare creditCardNumber: string; @Encrypted({ secretKey: process.env.ENCRYPTION_KEY || "default-key" }) + @Field("any") declare personalData: { ssn: string; birthDate: string; @@ -48,12 +50,14 @@ class UserCredentials extends Table.with(EncryptionModifier) { The `HashModifier` stores a one-way hash of field values. Unlike encryption, hashing is irreversible -- you cannot retrieve the original value. Use this for passwords and other sensitive data that only needs equality verification. ```typescript -import { Table, HashModifier, Hashed } from "@antelopejs/interface-database-decorators"; +import { Table, Field, HashModifier, Hashed } from "@antelopejs/interface-database-decorators"; class User extends Table.with(HashModifier) { + @Field("string") declare email: string; @Hashed({ algorithm: "sha256" }) + @Field("string") declare password: string; verifyPassword(plainPassword: string): boolean { @@ -89,15 +93,18 @@ Returns `true` if `value`, when hashed, matches the stored hash for the given fi The `LocalizationModifier` stores multiple language versions of a field value. Access a specific locale by calling `localize()` on the table instance. ```typescript -import { Table, LocalizationModifier, Localized } from "@antelopejs/interface-database-decorators"; +import { Table, Field, LocalizationModifier, Localized } from "@antelopejs/interface-database-decorators"; class Product extends Table.with(LocalizationModifier) { + @Field("number") declare price: number; @Localized({ fallbackLocale: "en" }) + @Field("string") declare name: string; @Localized({ fallbackLocale: "en" }) + @Field("string") declare description: string; } ``` @@ -164,6 +171,7 @@ Pass multiple modifier classes to `Table.with()`: ```typescript import { Table, + Field, EncryptionModifier, HashModifier, LocalizationModifier, @@ -174,15 +182,18 @@ import { class UserProfile extends Table.with(EncryptionModifier, HashModifier, LocalizationModifier) { @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" }) + @Field("any") declare privateInfo: { address: string; phoneNumber: string; }; @Hashed() + @Field("string") declare password: string; @Localized({ fallbackLocale: "en" }) + @Field("string") declare bio: string; } ```