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.
Files changed (116) hide show
  1. package/README.md +71 -33
  2. package/dist/auth/index.cjs +12 -2
  3. package/dist/auth/index.cjs.map +1 -1
  4. package/dist/auth/index.d.cts +13 -2
  5. package/dist/auth/index.d.ts +13 -2
  6. package/dist/auth/index.js +12 -2
  7. package/dist/chunk-277BSYVH.js +127 -0
  8. package/dist/chunk-277BSYVH.js.map +1 -0
  9. package/dist/chunk-6OGOVV57.js +3847 -0
  10. package/dist/chunk-6OGOVV57.js.map +1 -0
  11. package/dist/chunk-7YEX4MQV.cjs +38 -0
  12. package/dist/chunk-7YEX4MQV.cjs.map +1 -0
  13. package/dist/chunk-AZYXQU3Z.cjs +3847 -0
  14. package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
  15. package/dist/chunk-BUBXO7WU.js +170 -0
  16. package/dist/chunk-BUBXO7WU.js.map +1 -0
  17. package/dist/chunk-LJNSJFOL.js +38 -0
  18. package/dist/chunk-LJNSJFOL.js.map +1 -0
  19. package/dist/chunk-MGH4VDV3.cjs +170 -0
  20. package/dist/chunk-MGH4VDV3.cjs.map +1 -0
  21. package/dist/chunk-R34R7QPD.cjs +116 -0
  22. package/dist/chunk-R34R7QPD.cjs.map +1 -0
  23. package/dist/chunk-RS4MXCPW.js +116 -0
  24. package/dist/chunk-RS4MXCPW.js.map +1 -0
  25. package/dist/chunk-T4OHFU5T.cjs +154 -0
  26. package/dist/chunk-T4OHFU5T.cjs.map +1 -0
  27. package/dist/chunk-TI24L4XE.cjs.map +1 -1
  28. package/dist/chunk-TRC4DUZB.js +438 -0
  29. package/dist/chunk-TRC4DUZB.js.map +1 -0
  30. package/dist/chunk-TYR2GZZE.cjs +196 -0
  31. package/dist/chunk-TYR2GZZE.cjs.map +1 -0
  32. package/dist/chunk-UBQYQPBU.js +154 -0
  33. package/dist/chunk-UBQYQPBU.js.map +1 -0
  34. package/dist/chunk-UTM4PEVG.js +196 -0
  35. package/dist/chunk-UTM4PEVG.js.map +1 -0
  36. package/dist/chunk-YL37D6KM.cjs +127 -0
  37. package/dist/chunk-YL37D6KM.cjs.map +1 -0
  38. package/dist/chunk-ZDM5JHVK.cjs +438 -0
  39. package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
  40. package/dist/cli/db-runner.cjs +497 -0
  41. package/dist/cli/db-runner.cjs.map +1 -0
  42. package/dist/cli/db-runner.d.cts +2 -0
  43. package/dist/cli/db-runner.d.ts +2 -0
  44. package/dist/cli/db-runner.js +497 -0
  45. package/dist/cli/db-runner.js.map +1 -0
  46. package/dist/cli/index.cjs +447 -69
  47. package/dist/cli/index.cjs.map +1 -1
  48. package/dist/cli/index.js +473 -95
  49. package/dist/cli/index.js.map +1 -1
  50. package/dist/docs/api-reference/auth.md +232 -0
  51. package/dist/docs/api-reference/compose.md +78 -0
  52. package/dist/docs/api-reference/db.md +351 -0
  53. package/dist/docs/api-reference/http-error.md +109 -0
  54. package/dist/docs/api-reference/ignite.md +326 -0
  55. package/dist/docs/api-reference/table.md +458 -0
  56. package/dist/docs/api-reference/tasks.md +140 -0
  57. package/dist/docs/cli/db.md +38 -0
  58. package/dist/docs/cli/diagnostics.md +145 -0
  59. package/dist/docs/cli/generate.md +120 -0
  60. package/dist/docs/cli/index.md +48 -0
  61. package/dist/docs/cli/start.md +112 -0
  62. package/dist/docs/contributing/index.md +139 -0
  63. package/dist/docs/core-concepts/background-tasks.md +228 -0
  64. package/dist/docs/core-concepts/clustering.md +114 -0
  65. package/dist/docs/core-concepts/file-based-routing.md +235 -0
  66. package/dist/docs/core-concepts/index.md +79 -0
  67. package/dist/docs/core-concepts/middleware.md +144 -0
  68. package/dist/docs/getting-started/index.md +91 -0
  69. package/dist/docs/getting-started/project-structure.md +154 -0
  70. package/dist/docs/guides/ai-agents.md +48 -0
  71. package/dist/docs/guides/authentication.md +196 -0
  72. package/dist/docs/guides/caching.md +124 -0
  73. package/dist/docs/guides/database.md +217 -0
  74. package/dist/docs/guides/deployment.md +171 -0
  75. package/dist/docs/guides/environment-variables.md +106 -0
  76. package/dist/docs/guides/error-handling.md +172 -0
  77. package/dist/docs/guides/generated-portals.md +115 -0
  78. package/dist/docs/guides/logging.md +108 -0
  79. package/dist/docs/guides/mailer.md +166 -0
  80. package/dist/docs/guides/migrations.md +106 -0
  81. package/dist/docs/guides/rbac.md +89 -0
  82. package/dist/docs/guides/validation.md +95 -0
  83. package/dist/docs/index.md +93 -0
  84. package/dist/docs/skills/SKILL.md +44 -0
  85. package/dist/docs/skills/api-surface.md +309 -0
  86. package/dist/docs/skills/auth-internals.md +141 -0
  87. package/dist/docs/skills/pre-flight.md +142 -0
  88. package/dist/docs/skills/routing-rules.md +114 -0
  89. package/dist/docs/skills/tasks-internals.md +172 -0
  90. package/dist/docs/skills/what-not-to-invent.md +251 -0
  91. package/dist/index.cjs +264 -391
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +699 -7
  94. package/dist/index.d.ts +699 -7
  95. package/dist/index.js +258 -385
  96. package/dist/index.js.map +1 -1
  97. package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
  98. package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
  99. package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
  100. package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
  101. package/dist/tasks/index.cjs.map +1 -1
  102. package/dist/tasks/index.d.cts +1 -1
  103. package/dist/tasks/index.d.ts +1 -1
  104. package/dist/types-B6lVw4bj.d.cts +588 -0
  105. package/dist/types-B6lVw4bj.d.ts +588 -0
  106. package/package.json +28 -5
  107. package/dist/chunk-6522HS2J.cjs +0 -99
  108. package/dist/chunk-6522HS2J.cjs.map +0 -1
  109. package/dist/chunk-DGVOJNR6.cjs +0 -55
  110. package/dist/chunk-DGVOJNR6.cjs.map +0 -1
  111. package/dist/chunk-KOHLLUN7.js +0 -55
  112. package/dist/chunk-KOHLLUN7.js.map +0 -1
  113. package/dist/chunk-VIP3PFWZ.js +0 -99
  114. package/dist/chunk-VIP3PFWZ.js.map +0 -1
  115. package/dist/types-BusbSenn.d.cts +0 -162
  116. 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
+ ```