Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions .git-blame-ignore-revs
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Formatted with oxfmt when the repository moved off Biome.
6455daa739abafa590b36ffceb05a60f6131b956
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,6 @@ jobs:
- run: pnpm add --global @antelopejs/core
- run: pnpm prepack
- run: pnpm lint
- run: pnpm format:check
- run: pnpm knip
- run: pnpm test
8 changes: 4 additions & 4 deletions .github/workflows/stale.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
name: 'Close stale issues'
name: "Close stale issues"

on:
schedule:
- cron: '30 * * * *'
- cron: "30 * * * *"
workflow_dispatch:

permissions:
Expand All @@ -17,8 +17,8 @@ jobs:
- uses: actions/stale@v9
with:
exempt-issue-labels: pending
stale-issue-message: 'This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.'
close-issue-message: 'This issue was closed because it has been stalled for 30 days with no activity.'
stale-issue-message: "This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days."
close-issue-message: "This issue was closed because it has been stalled for 30 days with no activity."
days-before-stale: 60
days-before-close: 30
operations-per-run: 200
Expand Down
18 changes: 9 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
| --------------------- | --------------------------------------------------------------------------------------- |
| English only | All code must be in English: variable names, function names, comments |
| PNPM only | Always use pnpm, never npm or yarn |
| NO COMMENTS | Code must be self-documenting through clear naming. TSDoc is allowed for public APIs |
| NO COMMENTS | Code must be self-documenting through clear naming. TSDoc is allowed for public APIs |
| NO switch/case | Use objects, maps, or arrays instead |
| NO inline types | Define proper interfaces/types, never use anonymous types like `{a: string, b: number}` |
| Functions ≤ 40 lines | Split into subfunctions if longer |
Expand All @@ -35,23 +35,23 @@ Never use `switch/case` or `if param === 'XXX'` chains. Instead:
// BAD
function getStatus(code: string) {
switch (code) {
case 'A':
return 'Active';
case 'I':
return 'Inactive';
case "A":
return "Active";
case "I":
return "Inactive";
default:
return 'Unknown';
return "Unknown";
}
}

// GOOD
const STATUS_MAP: Record<string, string> = {
A: 'Active',
I: 'Inactive',
A: "Active",
I: "Inactive",
};

function getStatus(code: string) {
return STATUS_MAP[code] ?? 'Unknown';
return STATUS_MAP[code] ?? "Unknown";
}
```

Expand Down
3 changes: 0 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# Changelog


## v0.1.8

[compare changes](https://github.com/AntelopeJS/interface-data-api/compare/v0.1.7...v0.1.8)
Expand Down Expand Up @@ -175,7 +174,6 @@

## v0.0.2


### 🚀 Enhancements

- Add data API interface implementation ([f203c57](https://github.com/AntelopeJS/interface-data-api/commit/f203c57))
Expand All @@ -201,4 +199,3 @@

- Antony Rizzitelli <upd4ting@gmail.com>
- Glastis ([@Glastis](http://github.com/Glastis))

56 changes: 0 additions & 56 deletions biome.json

This file was deleted.

14 changes: 7 additions & 7 deletions docs/1.introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,13 +106,13 @@ class UserAPI extends DataController(

This generates the following REST endpoints:

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/users/get?id=<id>` | Retrieve a single user |
| GET | `/users/list?limit=10` | List users with pagination |
| POST | `/users/new` | Create a new user |
| PUT | `/users/edit?id=<id>` | Update an existing user |
| DELETE | `/users/delete?id=<id>` | Delete a user |
| Method | Endpoint | Description |
| ------ | ----------------------- | -------------------------- |
| GET | `/users/get?id=<id>` | Retrieve a single user |
| GET | `/users/list?limit=10` | List users with pagination |
| POST | `/users/new` | Create a new user |
| PUT | `/users/edit?id=<id>` | Update an existing user |
| DELETE | `/users/delete?id=<id>` | Delete a user |

## Documentation Sections

Expand Down
26 changes: 13 additions & 13 deletions docs/10.joined.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,13 +91,13 @@ A GET request to `/orders/get?id=order-123` returns the joined value at the top
@Joined({ table, localKey, remoteField, remoteIndex?, schema? })
```

| Option | Type | Required | Default | Description |
| ------ | ---- | -------- | ------- | ----------- |
| `table` | `Class<Table>` or `string` | Yes | - | The remote table class or registered table name string |
| `localKey` | `string` | Yes | - | The field on the local row holding the value matched against the remote table |
| `remoteField` | `string` | Yes | - | The remote field whose value is flattened onto the row |
| `remoteIndex` | `string` | No | `"_id"` | The index on the remote table to match `localKey` against |
| `schema` | `string` | No | Controller schema | Name of the schema the remote table is registered in, when it differs from the controller's schema |
| Option | Type | Required | Default | Description |
| ------------- | -------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| `table` | `Class<Table>` or `string` | Yes | - | The remote table class or registered table name string |
| `localKey` | `string` | Yes | - | The field on the local row holding the value matched against the remote table |
| `remoteField` | `string` | Yes | - | The remote field whose value is flattened onto the row |
| `remoteIndex` | `string` | No | `"_id"` | The index on the remote table to match `localKey` against |
| `schema` | `string` | No | Controller schema | Name of the schema the remote table is registered in, when it differs from the controller's schema |

## Sorting and Filtering

Expand Down Expand Up @@ -145,12 +145,12 @@ When a table class is passed, its schema is inferred from its `@RegisterTable` m

## Joined vs. Foreign

| Aspect | `@Joined` | `@Foreign` |
| ------ | --------- | ---------- |
| Result shape | A single scalar value flattened onto the row | The full referenced record (or plucked subset) nested under the field |
| Access | Read-only (enforced) | Configurable via `@Access` |
| Sort / filter | Native (join applied before sort/filter) | Not natively sortable/filterable on remote fields |
| Multiple references | One remote field per decorator | Single or array (`multi`) references |
| Aspect | `@Joined` | `@Foreign` |
| ------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| Result shape | A single scalar value flattened onto the row | The full referenced record (or plucked subset) nested under the field |
| Access | Read-only (enforced) | Configurable via `@Access` |
| Sort / filter | Native (join applied before sort/filter) | Not natively sortable/filterable on remote fields |
| Multiple references | One remote field per decorator | Single or array (`multi`) references |

## Next Steps

Expand Down
26 changes: 11 additions & 15 deletions docs/11.computed.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,7 @@ class GroupAPI extends DataController(
// Aggregate: number of devices referencing this group, computed in DB
@Listable()
@Computed(
(row, db) =>
db
.table("devices")
.getAll(row.key("_id"), "group_id")
.count(),
(row, db) => db.table("devices").getAll(row.key("_id"), "group_id").count(),
{ default: 0 },
)
@Sortable()
Expand Down Expand Up @@ -88,10 +84,10 @@ A GET request to `/groups/get?id=group-123` returns the computed values at the t
@Computed(expr, options?)
```

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `expr` | `(row, db) => expression` | Yes | Expression receiving the row proxy and the schema instance; returns a `ValueProxy` expression or a subquery (`Datum`) |
| `options.default` | `unknown` | No | Fallback merged over the computed value when the expression yields `null` |
| Parameter | Type | Required | Description |
| ----------------- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `expr` | `(row, db) => expression` | Yes | Expression receiving the row proxy and the schema instance; returns a `ValueProxy` expression or a subquery (`Datum`) |
| `options.default` | `unknown` | No | Fallback merged over the computed value when the expression yields `null` |

### The `default` option

Expand Down Expand Up @@ -134,12 +130,12 @@ declare devices_count: number;

## Computed vs. Joined

| Aspect | `@Computed` | `@Joined` |
| ------ | ----------- | --------- |
| Source | Arbitrary expression: row-local computation or per-row subquery | One scalar field from another table matched by a foreign key |
| Typical use | Aggregates (`count`, `sum`), derived values | Flattening a referenced record's field |
| Access | Read-only (enforced) | Read-only (enforced) |
| Sort / filter | Native, lazily injected only where needed | Native, always applied before sort/filter |
| Aspect | `@Computed` | `@Joined` |
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| Source | Arbitrary expression: row-local computation or per-row subquery | One scalar field from another table matched by a foreign key |
| Typical use | Aggregates (`count`, `sum`), derived values | Flattening a referenced record's field |
| Access | Read-only (enforced) | Read-only (enforced) |
| Sort / filter | Native, lazily injected only where needed | Native, always applied before sort/filter |

`@Joined` remains the simpler choice for the 1:1 flattening case; `@Computed` generalizes the same merge mechanism to arbitrary expressions.

Expand Down
8 changes: 4 additions & 4 deletions docs/2.data-controllers.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,11 +81,11 @@ DataController(
)
```

| Parameter | Description |
| --------- | ----------- |
| Parameter | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `tableClass` | The database table class decorated with `@RegisterTable`. The controller validates that this table exists in the database schema. |
| `routes` | An object mapping endpoint names to route callbacks. Use `DefaultRoutes.All` for standard CRUD or pass a custom subset. |
| `base` | The controller base, typically created with `Controller("/path")`, which sets the URL prefix for all endpoints. |
| `routes` | An object mapping endpoint names to route callbacks. Use `DefaultRoutes.All` for standard CRUD or pass a custom subset. |
| `base` | The controller base, typically created with `Controller("/path")`, which sets the URL prefix for all endpoints. |

## Required Components

Expand Down
Loading