Skip to content

docs: declare table fields with @Field and @Relation decorators in examples #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Upd4ting merged 2 commits into from
Jul 13, 2026
Merged

docs: declare table fields with @Field and @Relation decorators in examples #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3344800
docs: declare table fields with @Field and @Relation decorators in ex…
MrSociety404 Jul 13, 2026
8e3d970
docs: address greptile review feedback (greploop iteration 1)
MrSociety404 Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 41 additions & 7 deletions docs/2.table-definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
}
```
Expand All @@ -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;
}
```
Expand All @@ -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;
}
```
Expand All @@ -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";

Comment thread
MrSociety404 marked this conversation as resolved.
class User extends Table {
@Field("string")
declare name: string;
}

class UserActivity extends Table {
@Index({ group: "user_action" })
Comment thread
MrSociety404 marked this conversation as resolved.
@Field("string")
@Relation({ to: () => User })
declare userId: string;
Comment thread
MrSociety404 marked this conversation as resolved.

@Index({ group: "user_action" })
@Field("string")
declare action: string;

@Field("date")
Comment thread
MrSociety404 marked this conversation as resolved.
declare timestamp: Date;
}
```
Expand Down Expand Up @@ -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;
}
```
Expand All @@ -147,14 +165,15 @@ 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" },
{ _id: "user", name: "Standard User" },
{ _id: "guest", name: "Guest" },
])
class UserRole extends Table {
@Field("string")
declare name: string;
}
```
Expand All @@ -176,6 +195,7 @@ The generator function:
}));
})
class SystemConfig extends Table {
@Field("string")
declare value: string;
}
```
Expand All @@ -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
Comment thread
MrSociety404 marked this conversation as resolved.
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;
}
```
Expand Down
17 changes: 14 additions & 3 deletions docs/3.table-modifiers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,19 @@ 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({
secretKey: process.env.ENCRYPTION_KEY || "default-key",
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;
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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;
}
```
Expand Down Expand Up @@ -164,6 +171,7 @@ Pass multiple modifier classes to `Table.with()`:
```typescript
import {
Table,
Field,
EncryptionModifier,
HashModifier,
LocalizationModifier,
Expand All @@ -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;
}
```
Expand Down
Loading