From 3344800cbeb1f274043d36f6b8c30f7d6a9314fe Mon Sep 17 00:00:00 2001 From: MrSociety404 Date: Mon, 13 Jul 2026 11:32:55 +0200 Subject: [PATCH 1/2] docs: declare table fields with @Field and @Relation decorators in examples --- docs/2.table-definitions.md | 41 ++++++++++++++++++++++++++++++------- docs/3.table-modifiers.md | 17 ++++++++++++--- 2 files changed, 48 insertions(+), 10 deletions(-) diff --git a/docs/2.table-definitions.md b/docs/2.table-definitions.md index a589be4..c1f47b0 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,19 @@ 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 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 +140,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 +160,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 +168,7 @@ import { Table, Fixture } from "@antelopejs/interface-database-decorators"; { _id: "guest", name: "Guest" }, ]) class UserRole extends Table { + @Field("string") declare name: string; } ``` @@ -176,6 +190,7 @@ The generator function: })); }) class SystemConfig extends Table { + @Field("string") declare value: string; } ``` @@ -186,23 +201,35 @@ Tables support standard class inheritance. Define a base table with common field ```typescript 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; } ``` From 8e3d97050051fb19cc79c5c34318f5432514a1f7 Mon Sep 17 00:00:00 2001 From: MrSociety404 Date: Mon, 13 Jul 2026 11:46:08 +0200 Subject: [PATCH 2/2] docs: address greptile review feedback (greploop iteration 1) --- docs/2.table-definitions.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/2.table-definitions.md b/docs/2.table-definitions.md index c1f47b0..1cf4e8e 100644 --- a/docs/2.table-definitions.md +++ b/docs/2.table-definitions.md @@ -67,6 +67,11 @@ Assign multiple fields to the same index group to create a compound index: ```typescript 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") @@ -200,6 +205,8 @@ 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;