express-file-cluster 0.3.15 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -33
- package/dist/auth/index.cjs +12 -2
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +13 -2
- package/dist/auth/index.d.ts +13 -2
- package/dist/auth/index.js +12 -2
- package/dist/chunk-277BSYVH.js +127 -0
- package/dist/chunk-277BSYVH.js.map +1 -0
- package/dist/chunk-6OGOVV57.js +3847 -0
- package/dist/chunk-6OGOVV57.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-AZYXQU3Z.cjs +3847 -0
- package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
- package/dist/chunk-BUBXO7WU.js +170 -0
- package/dist/chunk-BUBXO7WU.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-MGH4VDV3.cjs +170 -0
- package/dist/chunk-MGH4VDV3.cjs.map +1 -0
- package/dist/chunk-R34R7QPD.cjs +116 -0
- package/dist/chunk-R34R7QPD.cjs.map +1 -0
- package/dist/chunk-RS4MXCPW.js +116 -0
- package/dist/chunk-RS4MXCPW.js.map +1 -0
- package/dist/chunk-T4OHFU5T.cjs +154 -0
- package/dist/chunk-T4OHFU5T.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-TRC4DUZB.js +438 -0
- package/dist/chunk-TRC4DUZB.js.map +1 -0
- package/dist/chunk-TYR2GZZE.cjs +196 -0
- package/dist/chunk-TYR2GZZE.cjs.map +1 -0
- package/dist/chunk-UBQYQPBU.js +154 -0
- package/dist/chunk-UBQYQPBU.js.map +1 -0
- package/dist/chunk-UTM4PEVG.js +196 -0
- package/dist/chunk-UTM4PEVG.js.map +1 -0
- package/dist/chunk-YL37D6KM.cjs +127 -0
- package/dist/chunk-YL37D6KM.cjs.map +1 -0
- package/dist/chunk-ZDM5JHVK.cjs +438 -0
- package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
- package/dist/cli/db-runner.cjs +497 -0
- package/dist/cli/db-runner.cjs.map +1 -0
- package/dist/cli/db-runner.d.cts +2 -0
- package/dist/cli/db-runner.d.ts +2 -0
- package/dist/cli/db-runner.js +497 -0
- package/dist/cli/db-runner.js.map +1 -0
- package/dist/cli/index.cjs +447 -69
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +473 -95
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +232 -0
- package/dist/docs/api-reference/compose.md +78 -0
- package/dist/docs/api-reference/db.md +351 -0
- package/dist/docs/api-reference/http-error.md +109 -0
- package/dist/docs/api-reference/ignite.md +326 -0
- package/dist/docs/api-reference/table.md +458 -0
- package/dist/docs/api-reference/tasks.md +140 -0
- package/dist/docs/cli/db.md +38 -0
- package/dist/docs/cli/diagnostics.md +145 -0
- package/dist/docs/cli/generate.md +120 -0
- package/dist/docs/cli/index.md +48 -0
- package/dist/docs/cli/start.md +112 -0
- package/dist/docs/contributing/index.md +139 -0
- package/dist/docs/core-concepts/background-tasks.md +228 -0
- package/dist/docs/core-concepts/clustering.md +114 -0
- package/dist/docs/core-concepts/file-based-routing.md +235 -0
- package/dist/docs/core-concepts/index.md +79 -0
- package/dist/docs/core-concepts/middleware.md +144 -0
- package/dist/docs/getting-started/index.md +91 -0
- package/dist/docs/getting-started/project-structure.md +154 -0
- package/dist/docs/guides/ai-agents.md +48 -0
- package/dist/docs/guides/authentication.md +196 -0
- package/dist/docs/guides/caching.md +124 -0
- package/dist/docs/guides/database.md +217 -0
- package/dist/docs/guides/deployment.md +171 -0
- package/dist/docs/guides/environment-variables.md +106 -0
- package/dist/docs/guides/error-handling.md +172 -0
- package/dist/docs/guides/generated-portals.md +115 -0
- package/dist/docs/guides/logging.md +108 -0
- package/dist/docs/guides/mailer.md +166 -0
- package/dist/docs/guides/migrations.md +106 -0
- package/dist/docs/guides/rbac.md +89 -0
- package/dist/docs/guides/validation.md +95 -0
- package/dist/docs/index.md +93 -0
- package/dist/docs/skills/SKILL.md +44 -0
- package/dist/docs/skills/api-surface.md +309 -0
- package/dist/docs/skills/auth-internals.md +141 -0
- package/dist/docs/skills/pre-flight.md +142 -0
- package/dist/docs/skills/routing-rules.md +114 -0
- package/dist/docs/skills/tasks-internals.md +172 -0
- package/dist/docs/skills/what-not-to-invent.md +251 -0
- package/dist/index.cjs +264 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +699 -7
- package/dist/index.d.ts +699 -7
- package/dist/index.js +258 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
- package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/types-B6lVw4bj.d.cts +588 -0
- package/dist/types-B6lVw4bj.d.ts +588 -0
- package/package.json +28 -5
- package/dist/chunk-6522HS2J.cjs +0 -99
- package/dist/chunk-6522HS2J.cjs.map +0 -1
- package/dist/chunk-DGVOJNR6.cjs +0 -55
- package/dist/chunk-DGVOJNR6.cjs.map +0 -1
- package/dist/chunk-KOHLLUN7.js +0 -55
- package/dist/chunk-KOHLLUN7.js.map +0 -1
- package/dist/chunk-VIP3PFWZ.js +0 -99
- package/dist/chunk-VIP3PFWZ.js.map +0 -1
- package/dist/types-BusbSenn.d.cts +0 -162
- package/dist/types-BusbSenn.d.ts +0 -162
|
@@ -0,0 +1,458 @@
|
|
|
1
|
+
# defineTable — API Reference
|
|
2
|
+
|
|
3
|
+
```ts
|
|
4
|
+
import { defineTable, type InferRecord } from 'express-file-cluster';
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
`defineTable` is EFC's **PostgreSQL-native** model API. It uses Prisma's query vocabulary
|
|
8
|
+
(`findMany({ where, orderBy, take, cursor })`, `findUnique`, `upsert`, `groupBy`, `aggregate`)
|
|
9
|
+
and SQL types (`integer`, `bigint`, `decimal`, `varchar`, native arrays and enums, serial ids).
|
|
10
|
+
Each call is a single parameterised SQL statement.
|
|
11
|
+
|
|
12
|
+
It shares the foundation with [`defineModel`](./db.md): the same schema format, validation,
|
|
13
|
+
automatic table sync, `transaction()`, errors and inferred types. Choose between them:
|
|
14
|
+
|
|
15
|
+
| | `defineModel` | `defineTable` |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| Engine | MongoDB **or** PostgreSQL | PostgreSQL only |
|
|
18
|
+
| Queries | MongoDB-style (`find(filter)`, `$gt`, `$inc`) | Prisma-style (`findMany({ where })`, `gt`, `increment`) |
|
|
19
|
+
| Types | portable set | + `integer`, `bigint`, `decimal`, `uuid`, `json`, `varchar`, native arrays/enums |
|
|
20
|
+
| Use it when | the app may switch engines | you're building on PostgreSQL |
|
|
21
|
+
|
|
22
|
+
On a MongoDB connection, the first call to a `defineTable` model throws an `[EFC]` error.
|
|
23
|
+
Calling a MongoDB-style method on a table (or a Prisma-style one on a `defineModel`) is a
|
|
24
|
+
compile error. A `defineModel` and a `defineTable` over the same table read and write the same
|
|
25
|
+
records (default naming, uuid ids), so you can move one model at a time.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## `defineTable(name, schema, options?)`
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
export const Order = defineTable(
|
|
33
|
+
'Order',
|
|
34
|
+
{
|
|
35
|
+
number: { type: 'string', required: true, unique: true, maxLength: 20 }, // varchar(20)
|
|
36
|
+
status: { type: 'string', enum: ['open', 'paid', 'shipped'], default: 'open', nativeEnum: true },
|
|
37
|
+
total: { type: 'decimal', precision: 10, scale: 2, required: true }, // numeric(10,2) → '19.99'
|
|
38
|
+
qty: { type: 'integer', required: true, min: 1 }, // integer
|
|
39
|
+
views: { type: 'bigint', default: 0n }, // bigint → 0n
|
|
40
|
+
tags: { type: 'array', of: 'string', default: [] }, // text[]
|
|
41
|
+
shipping: { city: { type: 'string', required: true }, zip: { type: 'string' } }, // jsonb
|
|
42
|
+
meta: { type: 'json' }, // jsonb, any JSON
|
|
43
|
+
customer: { type: 'uuid', required: true },
|
|
44
|
+
},
|
|
45
|
+
{ id: 'serial', naming: 'snake_case', indexes: [{ fields: { customer: 1, number: 1 }, unique: true }] },
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
export type Order = InferRecord<typeof Order>;
|
|
49
|
+
// { id: number; number: string; status: 'open' | 'paid' | 'shipped'; total: string; qty: number;
|
|
50
|
+
// views: bigint; tags: string[]; customer: string; shipping?: { city: string; zip?: string };
|
|
51
|
+
// meta?: unknown; createdAt: Date; updatedAt: Date }
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Field types
|
|
55
|
+
|
|
56
|
+
All the [`defineModel` field types and rules](./db.md#schema-fields) (`required`, `default`,
|
|
57
|
+
`enum`, `min`/`max`, `minLength`/`maxLength`, `match`, `validate`, `unique`, `index`,
|
|
58
|
+
`sequence`, nested objects, arrays of objects) also work here, plus:
|
|
59
|
+
|
|
60
|
+
| `type` | Column | JS value (reads) | Accepts on writes |
|
|
61
|
+
|---|---|---|---|
|
|
62
|
+
| `'integer'` | `integer` | `number` (32-bit, whole) | `number` |
|
|
63
|
+
| `'bigint'` | `bigint` | `bigint` | `bigint \| number` |
|
|
64
|
+
| `'decimal'` (`precision`, `scale`) | `numeric(p,s)` | `string`, exact | `string \| number` |
|
|
65
|
+
| `'uuid'` | `uuid` | `string` | `string` |
|
|
66
|
+
| `'json'` | `jsonb` | `unknown` | any JSON |
|
|
67
|
+
| `'string'` + `maxLength` | `varchar(n)` | `string` | `string` |
|
|
68
|
+
| `{ type: 'array', of: <scalar> }` | native array (`text[]`, `integer[]`, …) | `T[]` | `T[]` |
|
|
69
|
+
| `enum` + `nativeEnum: true` | PostgreSQL `ENUM` type | literal union | literal union |
|
|
70
|
+
|
|
71
|
+
Without `nativeEnum`, an `enum` is a `CHECK` constraint, as with `defineModel`. Arrays of nested
|
|
72
|
+
objects, embedded objects and `json` are stored as `jsonb`. `column: 'name'` sets a top-level
|
|
73
|
+
field's column name.
|
|
74
|
+
|
|
75
|
+
Responses from `ignite()` serialise `bigint` values as strings (`"9007199254740993"`).
|
|
76
|
+
|
|
77
|
+
### Options
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
interface TableOptions {
|
|
81
|
+
id?: 'uuid' | 'serial' | 'bigserial'; // default 'uuid'; serial → number ids, bigserial → bigint ids
|
|
82
|
+
naming?: 'snake_case'; // createdAt → created_at, OrderItem → order_items
|
|
83
|
+
timestamps?: boolean | { createdAt?: string | false; updatedAt?: string | false };
|
|
84
|
+
indexes?: { fields: Record<string, 1 | -1 | 'text'>; unique?: boolean; name?: string }[];
|
|
85
|
+
collection?: string; // table name
|
|
86
|
+
relations?: Record<string, { hasMany: string; foreignKey: string } | { hasOne: string; foreignKey: string }>; // see Include
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Schema sync
|
|
91
|
+
|
|
92
|
+
The table is created and kept in step on first use, with the same rules as `defineModel`. It
|
|
93
|
+
never drops columns or rows. On top of that:
|
|
94
|
+
|
|
95
|
+
- Native enum types are created, and new values are added. Values are never removed.
|
|
96
|
+
- `varchar` columns never shrink, and an existing `text` column is never narrowed.
|
|
97
|
+
- An existing `jsonb` array column (e.g. from `defineModel`) is converted to a native array,
|
|
98
|
+
keeping the data.
|
|
99
|
+
|
|
100
|
+
Preview the changes with `efc db sync --dry-run`.
|
|
101
|
+
|
|
102
|
+
### Foreign keys
|
|
103
|
+
|
|
104
|
+
A top-level `ref` field is a real foreign key to the referenced model's `id`:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
export const Author = defineTable('Author', { name: { type: 'string', required: true } });
|
|
108
|
+
export const Category = defineTable('Category', {
|
|
109
|
+
name: { type: 'string', required: true },
|
|
110
|
+
parent: { type: 'integer', ref: 'Category', onDelete: 'setNull' }, // self-relation
|
|
111
|
+
}, { id: 'serial' });
|
|
112
|
+
|
|
113
|
+
export const Post = defineTable('Post', {
|
|
114
|
+
title: { type: 'string', required: true },
|
|
115
|
+
author: { type: 'uuid', ref: 'Author', required: true, onDelete: 'cascade' },
|
|
116
|
+
reviewer: { type: 'uuid', ref: 'Author' }, // onDelete: 'restrict'
|
|
117
|
+
category: { type: 'integer', ref: 'Category' },
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
| `onDelete` | Deleting the referenced record… |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `'restrict'` (default) | is refused with a **409** while records point at it |
|
|
124
|
+
| `'cascade'` | deletes the records pointing at it too |
|
|
125
|
+
| `'setNull'` | clears the field on those records (not allowed on `required` fields) |
|
|
126
|
+
|
|
127
|
+
- The field's `type` must match the target's id: `uuid` (or `objectId`) for `id: 'uuid'`,
|
|
128
|
+
`integer` for `'serial'`, `bigint` for `'bigserial'`. A mismatch fails at first use, saying
|
|
129
|
+
which type to declare.
|
|
130
|
+
- Writing an id that doesn't exist is a **400** on that field (`author: Author not found`).
|
|
131
|
+
- Ref columns get an index (`<table>_<column>_idx`) unless `index: false`.
|
|
132
|
+
- The referenced model must be defined (imported) before the model that references it is used.
|
|
133
|
+
- The value is still the id: `post.author` is a string (or number). Loading the referenced
|
|
134
|
+
record with `include` comes next (M3b).
|
|
135
|
+
|
|
136
|
+
Sync creates a missing target table first, then adds the key `NOT VALID` (instant, and existing
|
|
137
|
+
rows can't fail the deploy) and validates it right after the commit. If old rows point at
|
|
138
|
+
records that no longer exist, validation is skipped with a warning naming the count. The key
|
|
139
|
+
still applies to new writes; fix the rows and run `efc db sync` to validate it. Changing
|
|
140
|
+
`onDelete` replaces the key, and removing `ref` drops it. Foreign keys on columns the model
|
|
141
|
+
doesn't declare are left alone.
|
|
142
|
+
|
|
143
|
+
`defineModel` keeps `ref` portable: on PostgreSQL it stays a plain column with no foreign key,
|
|
144
|
+
the same as on MongoDB.
|
|
145
|
+
|
|
146
|
+
### Many-to-many
|
|
147
|
+
|
|
148
|
+
An array of refs is a many-to-many relation:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
export const Tag = defineTable('Tag', { label: { type: 'string', required: true, unique: true } });
|
|
152
|
+
export const Post = defineTable('Post', {
|
|
153
|
+
title: { type: 'string', required: true },
|
|
154
|
+
tags: { type: 'array', of: 'uuid', ref: 'Tag' }, // of: matches Tag's id type
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
const post = await Post.create({ data: { title: 'Hello', tags: [news, tech] } });
|
|
158
|
+
post.tags; // [news, tech] — ids, in order
|
|
159
|
+
await Post.findMany({ where: { tags: { has: tech } } });
|
|
160
|
+
await Post.update({ where: { id: post.id }, data: { tags: { push: launch } } });
|
|
161
|
+
await Post.update({ where: { id: post.id }, data: { tags: { set: [tech] } } });
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
- Records keep the list of ids (`string[]`, `number[]` or `bigint[]`), in the order written, without
|
|
165
|
+
duplicates. New records start with `[]`.
|
|
166
|
+
- Filters are the list filters: `has`, `hasSome`, `hasEvery`, `isEmpty`, `equals`. Updates take a
|
|
167
|
+
list, `{ set: [...] }` or `{ push: id | [...] }` (ids already linked are left in place).
|
|
168
|
+
`select` / `omit` work as for any field. Ordering, grouping and `_sum`-style aggregates on the
|
|
169
|
+
field are refused.
|
|
170
|
+
- The links live in a join table, `<table>_<column>` (`posts_tags`): `owner_id`, `ref_id`,
|
|
171
|
+
`position`, primary key `(owner_id, ref_id)`, an index on `ref_id`, and foreign keys to both
|
|
172
|
+
tables with `ON DELETE CASCADE`. Deleting a post or a tag removes its links (a deleted tag
|
|
173
|
+
disappears from every post's `tags`). There is no `onDelete` option for these fields.
|
|
174
|
+
- An id that doesn't exist is a **400** on the field, and nothing is written.
|
|
175
|
+
- Reads stay one statement (the list is a subquery). A write that changes links runs in a
|
|
176
|
+
transaction: the row, then the links.
|
|
177
|
+
- Self-relations work (`friends: { type: 'array', of: 'uuid', ref: 'Person' }`).
|
|
178
|
+
|
|
179
|
+
**Moving from an array column.** If the table already stores the field as an array (`uuid[]`,
|
|
180
|
+
or `jsonb` from `defineModel`), the first sync copies it into the join table, keeping the order
|
|
181
|
+
and skipping values that aren't ids. The old column stays (sync never drops columns) but is no
|
|
182
|
+
longer read or written, so a `defineModel` over the same table won't see later changes to the
|
|
183
|
+
list.
|
|
184
|
+
|
|
185
|
+
### Include
|
|
186
|
+
|
|
187
|
+
`include` loads related records into the result: a `ref` field becomes the record it points at,
|
|
188
|
+
a many-to-many field the list of records, and back-relations — declared with `relations` —
|
|
189
|
+
the records pointing here.
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
export const User = defineTable('User', { email: { type: 'string', required: true, unique: true } }, {
|
|
193
|
+
relations: {
|
|
194
|
+
posts: { hasMany: 'Post', foreignKey: 'author' }, // Post.author refs User
|
|
195
|
+
profile: { hasOne: 'Profile', foreignKey: 'user' }, // Profile.user refs User, unique
|
|
196
|
+
},
|
|
197
|
+
});
|
|
198
|
+
export const Tag = defineTable('Tag', { label: { type: 'string', required: true } }, {
|
|
199
|
+
relations: { posts: { hasMany: 'Post', foreignKey: 'tags' } }, // through Post.tags (m:n)
|
|
200
|
+
});
|
|
201
|
+
|
|
202
|
+
const users = await User.findMany({
|
|
203
|
+
include: {
|
|
204
|
+
profile: true,
|
|
205
|
+
posts: {
|
|
206
|
+
where: { published: true },
|
|
207
|
+
orderBy: { createdAt: 'desc' },
|
|
208
|
+
take: 5,
|
|
209
|
+
select: { title: true },
|
|
210
|
+
include: { tags: { select: { label: true } } },
|
|
211
|
+
},
|
|
212
|
+
},
|
|
213
|
+
});
|
|
214
|
+
// [{ id, email, …, profile: { … } | null, posts: [{ title, tags: [{ label }] }] }]
|
|
215
|
+
|
|
216
|
+
await Post.findUnique({ where: { id }, include: { author: true } }); // author: { … } | null
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
| Relation | Declared as | `include` gives |
|
|
220
|
+
|---|---|---|
|
|
221
|
+
| belongs to | `author: { type: 'uuid', ref: 'User' }` | the record, or `null` (never `null` when `required`) |
|
|
222
|
+
| many-to-many | `tags: { type: 'array', of: 'uuid', ref: 'Tag' }` | the records, in link order |
|
|
223
|
+
| has many | `relations: { posts: { hasMany: 'Post', foreignKey: 'author' } }` | the records (by `id` unless `orderBy`) |
|
|
224
|
+
| has one | `relations: { profile: { hasOne: 'Profile', foreignKey: 'user' } }` | the record or `null` — `foreignKey` must be `unique` |
|
|
225
|
+
|
|
226
|
+
- `true`, or options: `select`, `omit`, a nested `include` (any depth), and on lists `where`,
|
|
227
|
+
`orderBy`, `take`, `skip`. `false` leaves the relation out.
|
|
228
|
+
- `foreignKey` names the field on the other model that refs this one: a scalar `ref` or a
|
|
229
|
+
many-to-many array.
|
|
230
|
+
- **One statement per call**, whatever the depth: each relation is a correlated subquery
|
|
231
|
+
building `jsonb`. Included records read exactly like direct reads (`bigint`s, decimals as
|
|
232
|
+
strings, dates).
|
|
233
|
+
- `findMany`, `findFirst`, `findUnique` (and `…OrThrow`), `create`, `update`, `upsert` and
|
|
234
|
+
`delete` take `include`. Writes read the record back with its relations after writing;
|
|
235
|
+
`delete` reads it first.
|
|
236
|
+
- Self-relations work both ways (`parent` ref + `children: { hasMany: 'Category', foreignKey: 'parent' }`).
|
|
237
|
+
|
|
238
|
+
**Types.** Relations name models by string, so register your models once for typed includes:
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
declare module 'express-file-cluster' {
|
|
242
|
+
interface Tables { User: typeof User; Post: typeof Post; Tag: typeof Tag; Profile: typeof Profile }
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Included records are then typed (`select` / `omit` / nested `include` applied), and `include`
|
|
247
|
+
keys, nested `where` and `orderBy` are checked. A relation to an unregistered model still works,
|
|
248
|
+
typed as `Record<string, unknown>`.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Reading
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
findMany(args?) → Record[]
|
|
256
|
+
findFirst(args?) → Record | null
|
|
257
|
+
findFirstOrThrow(args?) → Record // 404 HttpError if none
|
|
258
|
+
findUnique({ where }) → Record | null // where must name a unique key
|
|
259
|
+
findUniqueOrThrow({ where }) → Record // 404 HttpError if none
|
|
260
|
+
count(args?) → number // or { _all, field… } with select
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
const page = await Order.findMany({
|
|
265
|
+
where: {
|
|
266
|
+
status: { in: ['paid', 'shipped'] },
|
|
267
|
+
total: { gte: '100' },
|
|
268
|
+
customer: id,
|
|
269
|
+
OR: [{ number: { startsWith: 'EU-' } }, { tags: { has: 'priority' } }],
|
|
270
|
+
},
|
|
271
|
+
orderBy: [{ createdAt: 'desc' }, { qty: { sort: 'asc', nulls: 'last' } }],
|
|
272
|
+
take: 20,
|
|
273
|
+
skip: 20,
|
|
274
|
+
select: { id: true, number: true, total: true }, // result type narrows to these
|
|
275
|
+
});
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
| Argument | |
|
|
279
|
+
|---|---|
|
|
280
|
+
| `where` | filters (below) |
|
|
281
|
+
| `orderBy` | `{ field: 'asc' \| 'desc' }`, `{ field: { sort, nulls: 'first' \| 'last' } }`, or an array |
|
|
282
|
+
| `take` / `skip` | page size / offset. A negative `take` reads backwards. |
|
|
283
|
+
| `cursor` | a unique `where` (`{ id }`). The page starts **at** that record; add `skip: 1` to start after it. |
|
|
284
|
+
| `distinct` | `['field', …]`: the first record per distinct combination, in `orderBy` order |
|
|
285
|
+
| `select` / `omit` | `{ field: true }`: keep, or leave out, these fields. The result type follows. |
|
|
286
|
+
|
|
287
|
+
Pages are ordered deterministically: when `take`, `skip` or `cursor` is used, ties are broken
|
|
288
|
+
by `id`. Cursors work with any `orderBy`, including mixed directions and nullable columns.
|
|
289
|
+
|
|
290
|
+
```ts
|
|
291
|
+
// Cursor pagination
|
|
292
|
+
const next = await Order.findMany({ orderBy: { qty: 'desc' }, take: 20, cursor: { id: last }, skip: 1 });
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
### Filters
|
|
296
|
+
|
|
297
|
+
| Field kind | Filters |
|
|
298
|
+
|---|---|
|
|
299
|
+
| any scalar | a value (equality), `null`, `equals`, `not`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte` |
|
|
300
|
+
| strings | + `contains`, `startsWith`, `endsWith`, `mode: 'insensitive'` (ILIKE) |
|
|
301
|
+
| native arrays | `has`, `hasEvery`, `hasSome`, `isEmpty`, `equals` |
|
|
302
|
+
| objects / arrays of objects / `json` | `equals`, `not`, and with `path: ['a', 'b']`: `equals`, `string_contains`, `string_starts_with`, `string_ends_with`, `array_contains`, `gt`… |
|
|
303
|
+
| relations, to-many (many-to-many fields, `hasMany`) | `some`, `every`, `none` — each a `where` on the related model |
|
|
304
|
+
| relations, to-one (ref fields, `hasOne`) | `is`, `isNot` — a `where` on the related model, or `null` |
|
|
305
|
+
| combinators | `AND`, `OR`, `NOT` (an object or an array) |
|
|
306
|
+
|
|
307
|
+
```ts
|
|
308
|
+
await User.findMany({ where: { posts: { some: { comments: { some: { approved: false } } } } } });
|
|
309
|
+
await User.findMany({ where: { posts: { none: {} } } }); // users without posts
|
|
310
|
+
await Post.findMany({ where: { author: { is: { role: 'admin' } }, tags: { every: { public: true } } } });
|
|
311
|
+
await Post.findMany({ where: { author: { is: null } } }); // no author
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Relation filters are `EXISTS` subqueries — the read stays one statement — and nest to any
|
|
315
|
+
depth. They work wherever `where` does: reads, `count`, `include`, `updateMany`, `deleteMany`.
|
|
316
|
+
`every` holds for records with no related records at all. A ref or many-to-many field still
|
|
317
|
+
takes its own id filters (`author: id`, `tags: { has: id }`); a back-relation only these.
|
|
318
|
+
|
|
319
|
+
`undefined` values are ignored. Filters on undeclared fields match nothing, as with
|
|
320
|
+
`defineModel`. `LIKE` wildcards in `contains`, `startsWith` and `endsWith` are escaped.
|
|
321
|
+
|
|
322
|
+
### Unique lookups
|
|
323
|
+
|
|
324
|
+
`findUnique`, `update`, `upsert`, `delete` and `cursor` take a `where` that names one record:
|
|
325
|
+
`id`, a `unique: true` field, or every field of a `unique` index (e.g. `{ customer, number }`).
|
|
326
|
+
Other filters may be added. A `where` that isn't unique doesn't compile, and at runtime it
|
|
327
|
+
throws a `ModelValidationError`.
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## Writing
|
|
332
|
+
|
|
333
|
+
```ts
|
|
334
|
+
create({ data, select?, omit? }) → Record
|
|
335
|
+
createMany({ data: [...], skipDuplicates? }) → { count }
|
|
336
|
+
createManyAndReturn({ data: [...], select? }) → Record[]
|
|
337
|
+
update({ where: unique, data, select? }) → Record // 404 if missing
|
|
338
|
+
updateMany({ where?, data }) → { count }
|
|
339
|
+
updateManyAndReturn({ where?, data, select? }) → Record[]
|
|
340
|
+
upsert({ where: unique, create, update, select? }) → Record
|
|
341
|
+
delete({ where: unique }) → Record // 404 if missing
|
|
342
|
+
deleteMany({ where? }) → { count }
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
```ts
|
|
346
|
+
await Order.update({
|
|
347
|
+
where: { number: 'EU-1' },
|
|
348
|
+
data: {
|
|
349
|
+
status: 'paid',
|
|
350
|
+
qty: { increment: 1 }, // decrement, multiply, divide — number fields
|
|
351
|
+
views: { increment: 1n },
|
|
352
|
+
total: { decrement: '5.00' }, // exact on decimals
|
|
353
|
+
tags: { push: 'priority' }, // or an array; on native arrays
|
|
354
|
+
shipping: { city: 'Oslo' }, // jsonb fields take whole values
|
|
355
|
+
meta: null, // null unsets an optional field
|
|
356
|
+
},
|
|
357
|
+
});
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
- **`upsert`** is a single `INSERT … ON CONFLICT (<unique key>) DO UPDATE`, so it's atomic and
|
|
361
|
+
race-free. Key values from `where` fill `create` when they're missing there.
|
|
362
|
+
- **`createMany({ skipDuplicates: true })`** → `ON CONFLICT DO NOTHING`.
|
|
363
|
+
- Writes are validated like `defineModel` writes: type, `enum`, bounds, `integer` range,
|
|
364
|
+
`decimal` precision/scale, `maxLength` and `validate`. Failures throw `ModelValidationError`
|
|
365
|
+
(400); a duplicate unique value gives a 409. `updatedAt` is refreshed on every update.
|
|
366
|
+
`increment`/`decrement` results are not re-checked against `min`/`max`.
|
|
367
|
+
|
|
368
|
+
### Nested writes
|
|
369
|
+
|
|
370
|
+
`create`, `update` and `upsert` can write related records in the same call:
|
|
371
|
+
|
|
372
|
+
```ts
|
|
373
|
+
await Post.create({
|
|
374
|
+
data: {
|
|
375
|
+
title: 'Hello',
|
|
376
|
+
author: { connect: { email: 'ann@x.io' } }, // a ref: connect / create / connectOrCreate
|
|
377
|
+
tags: { // many-to-many
|
|
378
|
+
connect: [{ label: 'news' }],
|
|
379
|
+
connectOrCreate: [{ where: { label: 'tech' }, create: { label: 'tech' } }],
|
|
380
|
+
create: [{ label: 'launch' }],
|
|
381
|
+
},
|
|
382
|
+
comments: { create: [{ body: 'First!' }] }, // a back-relation (hasMany)
|
|
383
|
+
},
|
|
384
|
+
include: { author: true, tags: true, comments: true },
|
|
385
|
+
});
|
|
386
|
+
|
|
387
|
+
await User.update({
|
|
388
|
+
where: { id },
|
|
389
|
+
data: {
|
|
390
|
+
posts: { connect: [{ id: p1 }], disconnect: [{ id: p2 }], deleteMany: { draft: true } },
|
|
391
|
+
profile: { create: { bio: 'hi' } }, // hasOne: replaces the current one
|
|
392
|
+
},
|
|
393
|
+
});
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
| Relation | `create` | `update` adds |
|
|
397
|
+
|---|---|---|
|
|
398
|
+
| ref field | `connect`, `create`, `connectOrCreate` (or the id) | `disconnect: true` |
|
|
399
|
+
| many-to-many field | `connect`, `create`, `connectOrCreate` (or ids) | `disconnect`, `set`, `push`, `pull` |
|
|
400
|
+
| `hasMany` | `connect`, `create` | `disconnect`, `set`, `delete`, `deleteMany` |
|
|
401
|
+
| `hasOne` | `connect`, `create` | `disconnect: true`, `delete: true` |
|
|
402
|
+
|
|
403
|
+
- `connect`, `disconnect`, `set` and `delete` take unique wheres (or ids); a list or a single one.
|
|
404
|
+
A `connect` that matches nothing is a **400** on the field.
|
|
405
|
+
- Children created through a back-relation get their foreign key from the parent — leave it out.
|
|
406
|
+
- The whole call runs in **one transaction**: anything failing rolls it all back.
|
|
407
|
+
- `createMany` / `updateMany` write rows only; they refuse nested writes, as in Prisma.
|
|
408
|
+
- `upsert` with nested writes reads first, then creates or updates, in the transaction (without
|
|
409
|
+
nested writes it stays a single `INSERT … ON CONFLICT`).
|
|
410
|
+
- A model first used inside a transaction gets its table right away and its foreign keys once
|
|
411
|
+
the transaction commits, so the sync never waits on the transaction's own locks.
|
|
412
|
+
|
|
413
|
+
---
|
|
414
|
+
|
|
415
|
+
## Aggregation
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
const stats = await Order.aggregate({
|
|
419
|
+
where: { status: 'paid' },
|
|
420
|
+
_count: true,
|
|
421
|
+
_sum: { total: true, qty: true },
|
|
422
|
+
_avg: { qty: true },
|
|
423
|
+
_min: { createdAt: true },
|
|
424
|
+
_max: { total: true },
|
|
425
|
+
});
|
|
426
|
+
// { _count: number; _sum: { total: string | null; qty: number | null }; _avg: { qty: number | null };
|
|
427
|
+
// _min: { createdAt: Date | null }; _max: { total: string | null } }
|
|
428
|
+
|
|
429
|
+
const byStatus = await Order.groupBy({
|
|
430
|
+
by: ['status'],
|
|
431
|
+
where: { createdAt: { gte: since } },
|
|
432
|
+
_count: { _all: true },
|
|
433
|
+
_sum: { total: true },
|
|
434
|
+
having: { total: { _sum: { gt: 1000 } } },
|
|
435
|
+
orderBy: { _sum: { total: 'desc' } },
|
|
436
|
+
take: 10,
|
|
437
|
+
});
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
| Aggregate | Applies to | Returns |
|
|
441
|
+
|---|---|---|
|
|
442
|
+
| `_count` | `true` or `{ _all, field }` | `number` (non-null values per field) |
|
|
443
|
+
| `_sum` | number fields | `integer`/`number` → `number`, `bigint` → `bigint`, `decimal` → `string` |
|
|
444
|
+
| `_avg` | number fields | `number`; `decimal` → `string` |
|
|
445
|
+
| `_min` / `_max` | scalar fields | the field's type |
|
|
446
|
+
|
|
447
|
+
Over an empty set, `_sum`, `_avg`, `_min` and `_max` are `null`. `aggregate` also takes
|
|
448
|
+
`orderBy`, `take`, `skip` and `cursor`, and then aggregates over that page.
|
|
449
|
+
|
|
450
|
+
---
|
|
451
|
+
|
|
452
|
+
## Also
|
|
453
|
+
|
|
454
|
+
- `raw()` returns the Drizzle `pgTable`, for anything EFC doesn't cover.
|
|
455
|
+
- `sync({ dryRun })` / `drop()` work as with `defineModel`.
|
|
456
|
+
- `transaction(async () => …)` covers `defineTable` calls too.
|
|
457
|
+
- Relations are complete: foreign keys, many-to-many, `include`, relation filters and nested
|
|
458
|
+
writes (above).
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Tasks — API Reference
|
|
2
|
+
|
|
3
|
+
Task functions are exported from the `tasks` sub-path:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { defineTask, enqueue } from 'express-file-cluster/tasks';
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## `defineTask(handler)` / `defineTask(options, handler)`
|
|
12
|
+
|
|
13
|
+
Creates a `TaskDefinition`. The file's default export must be a `TaskDefinition` for EFC to register the task.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
// Overloads
|
|
17
|
+
defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
18
|
+
defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Minimal task
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { defineTask } from 'express-file-cluster/tasks';
|
|
25
|
+
|
|
26
|
+
export default defineTask<{ userId: string }>(async ({ userId }) => {
|
|
27
|
+
await sendWelcomeEmail(userId);
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Task with options
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { defineTask } from 'express-file-cluster/tasks';
|
|
35
|
+
|
|
36
|
+
export default defineTask<{ key: string; width: number }>(
|
|
37
|
+
{
|
|
38
|
+
thread: true, // run in worker_threads
|
|
39
|
+
retries: 5,
|
|
40
|
+
backoff: 'exponential',
|
|
41
|
+
concurrency: 2,
|
|
42
|
+
},
|
|
43
|
+
async ({ key, width }) => {
|
|
44
|
+
await resizeImage(key, width);
|
|
45
|
+
},
|
|
46
|
+
);
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## `TaskOptions`
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
interface TaskOptions {
|
|
55
|
+
thread?: boolean;
|
|
56
|
+
retries?: number;
|
|
57
|
+
backoff?: 'fixed' | 'exponential';
|
|
58
|
+
concurrency?: number;
|
|
59
|
+
schedule?: string;
|
|
60
|
+
timezone?: string;
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
| Option | Type | Default | Description |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| `thread` | `boolean` | `false` | Run handler in a `worker_threads` thread. Use for CPU-bound work. |
|
|
67
|
+
| `retries` | `number` | `3` | Re-runs after the first failed attempt, so a job runs at most `retries + 1` times before it is dead-lettered. |
|
|
68
|
+
| `backoff` | `'fixed' \| 'exponential'` | `'exponential'` | Retry delay strategy. Exponential starts at 1 second and doubles. |
|
|
69
|
+
| `concurrency` | `number` | `tasks.concurrency` from `ignite()` | Maximum parallel jobs of this type. |
|
|
70
|
+
| `schedule` | `string` | — | Cron pattern, e.g. `'*/15 * * * *'`. Scheduled runs receive `{}` as the payload. |
|
|
71
|
+
| `timezone` | `string` | server time | IANA timezone for `schedule`. |
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## `enqueue(name, payload)`
|
|
76
|
+
|
|
77
|
+
Adds a job to the task queue.
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
async function enqueue<T>(name: string, payload: T): Promise<void>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
| Parameter | Type | Description |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| `name` | `string` | Task name — the filename without extension (e.g. `'SendEmail'`) |
|
|
86
|
+
| `payload` | `T` | Data passed to the task handler |
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { enqueue } from 'express-file-cluster/tasks';
|
|
90
|
+
|
|
91
|
+
await enqueue('SendEmail', {
|
|
92
|
+
to: 'alice@example.com',
|
|
93
|
+
subject: 'Welcome!',
|
|
94
|
+
body: 'Thanks for signing up.',
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`enqueue` rejects if:
|
|
99
|
+
|
|
100
|
+
- **Task backend not initialised** — `tasks` was not configured in `ignite()`.
|
|
101
|
+
- **Unknown task name** — no file with that basename exists in `src/tasks/`.
|
|
102
|
+
- **The queue backend is unreachable** — Redis (BullMQ) or PostgreSQL (pg-boss) didn't accept the job within `tasks.enqueueTimeout` (default 5000 ms). It never waits indefinitely, and a rejected job is not queued later behind your back, so it is safe to retry or return a 503.
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
try {
|
|
106
|
+
await enqueue('SendEmail', payload);
|
|
107
|
+
} catch (err) {
|
|
108
|
+
throw new HttpError(503, 'Queue unavailable, try again shortly');
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## `TaskDefinition<T>`
|
|
115
|
+
|
|
116
|
+
The shape returned by `defineTask` and stored in the registry:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
interface TaskDefinition<TPayload = unknown> {
|
|
120
|
+
handler: (payload: TPayload) => Promise<void>;
|
|
121
|
+
options: TaskOptions;
|
|
122
|
+
name: string; // set by scanTasks — empty string from defineTask itself
|
|
123
|
+
filePath?: string; // set by scanTasks — used by the thread runner
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
You do not construct `TaskDefinition` directly — always use `defineTask`.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Task name resolution
|
|
132
|
+
|
|
133
|
+
The task name is the **file's basename without extension**:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
src/tasks/SendEmail.ts → "SendEmail"
|
|
137
|
+
src/tasks/ResizeImage.ts → "ResizeImage"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The name is case-sensitive. `enqueue('sendEmail', ...)` will not match `SendEmail.ts`.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# `efc db`
|
|
2
|
+
|
|
3
|
+
Database migrations, seeds and studio. Works on MongoDB and PostgreSQL — the engine follows the `DATABASE_URL` scheme. Full guide: [Migrations & Seeds](../guides/migrations.md).
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
efc db sync [--dry-run] # reconcile tables/collections + indexes with src/model(s)/
|
|
7
|
+
efc db migrate # run pending migrations (one new batch)
|
|
8
|
+
efc db rollback [--steps 2] # revert the last batch(es)
|
|
9
|
+
efc db status # applied vs pending
|
|
10
|
+
efc db seed [name] # run all seeds, or one
|
|
11
|
+
efc db studio [--port 4983] # read-only browser on 127.0.0.1 (rows + table structure)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Common options
|
|
15
|
+
|
|
16
|
+
| Option | Meaning |
|
|
17
|
+
|---|---|
|
|
18
|
+
| `--database-url <url>` | Override `DATABASE_URL` (otherwise read from the environment, then `.env`) |
|
|
19
|
+
| `--dist` | Load compiled files from `dist/src/` even when `tsx` is installed |
|
|
20
|
+
|
|
21
|
+
## Where files load from
|
|
22
|
+
|
|
23
|
+
| Situation | Runs | From |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `tsx` installed (dev) | `tsx` | `src/migrations`, `src/seeds` |
|
|
26
|
+
| No `tsx` (production image) | `node` | `dist/src/migrations`, `dist/src/seeds` |
|
|
27
|
+
| JavaScript project | `node` | `src/` |
|
|
28
|
+
|
|
29
|
+
## Exit codes
|
|
30
|
+
|
|
31
|
+
`0` on success, `1` on any failure (connection, a throwing migration/seed, missing `down()` on rollback). Set `EFC_DEBUG=1` for stack traces.
|
|
32
|
+
|
|
33
|
+
## Scaffolding
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
efc generate migration <name> # src/migrations/<UTC timestamp>_<name>.ts
|
|
37
|
+
efc generate seed <name> # src/seeds/<name>.ts
|
|
38
|
+
```
|