express-file-cluster 0.9.6 → 0.10.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/dist/auth/index.cjs +5 -5
- package/dist/auth/index.d.cts +1 -1
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.js +4 -4
- package/dist/{chunk-QL6EWT4B.cjs → chunk-4DOHQU6I.cjs} +9 -7
- package/dist/chunk-4DOHQU6I.cjs.map +1 -0
- package/dist/{chunk-2SETEVMO.js → chunk-7KC2H76D.js} +42 -2
- package/dist/chunk-7KC2H76D.js.map +1 -0
- package/dist/{chunk-6KHBJOLB.cjs → chunk-7KO4DJRJ.cjs} +7 -7
- package/dist/{chunk-6KHBJOLB.cjs.map → chunk-7KO4DJRJ.cjs.map} +1 -1
- package/dist/{chunk-45BWAR6P.js → chunk-ATVD2HGC.js} +3 -3
- package/dist/{chunk-BBSZLGZW.js → chunk-EGSSZUVO.js} +8 -6
- package/dist/chunk-EGSSZUVO.js.map +1 -0
- package/dist/{chunk-TI24L4XE.cjs → chunk-GBI77W5T.cjs} +6 -2
- package/dist/chunk-GBI77W5T.cjs.map +1 -0
- package/dist/{chunk-VWSUQKCJ.cjs → chunk-HBCY7ILD.cjs} +274 -107
- package/dist/chunk-HBCY7ILD.cjs.map +1 -0
- package/dist/{chunk-RGT4ZVHL.cjs → chunk-KFVFP2Q7.cjs} +45 -5
- package/dist/chunk-KFVFP2Q7.cjs.map +1 -0
- package/dist/{chunk-TYCYYLLM.cjs → chunk-NKLOE4AK.cjs} +1 -1
- package/dist/chunk-NKLOE4AK.cjs.map +1 -0
- package/dist/{chunk-OFA7OGN5.js → chunk-PGJQK36V.js} +171 -4
- package/dist/chunk-PGJQK36V.js.map +1 -0
- package/dist/{chunk-ULWNHN6P.js → chunk-QDEDOHP7.js} +1 -1
- package/dist/chunk-QDEDOHP7.js.map +1 -0
- package/dist/{chunk-7ZESZG3J.js → chunk-R4XO4SVM.js} +3 -3
- package/dist/chunk-R52CUEGT.js +74 -0
- package/dist/chunk-R52CUEGT.js.map +1 -0
- package/dist/{chunk-HBYSKULC.js → chunk-RAB44UGX.js} +5 -1
- package/dist/chunk-RAB44UGX.js.map +1 -0
- package/dist/{chunk-7YEX4MQV.cjs → chunk-WBLUGOAG.cjs} +42 -6
- package/dist/chunk-WBLUGOAG.cjs.map +1 -0
- package/dist/{chunk-FMA76PRH.cjs → chunk-YK4ZM3CA.cjs} +8 -8
- package/dist/{chunk-FMA76PRH.cjs.map → chunk-YK4ZM3CA.cjs.map} +1 -1
- package/dist/cli/db-runner.cjs +2010 -116
- package/dist/cli/db-runner.cjs.map +1 -1
- package/dist/cli/db-runner.js +1987 -93
- package/dist/cli/db-runner.js.map +1 -1
- package/dist/cli/index.cjs +36 -13
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +33 -10
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/collection.md +44 -1
- package/dist/docs/api-reference/ignite.md +9 -0
- package/dist/docs/api-reference/types.md +99 -0
- package/dist/docs/cli/add.md +1 -1
- package/dist/docs/cli/db.md +2 -2
- package/dist/docs/core-concepts/background-tasks.md +6 -3
- package/dist/docs/getting-started/index.md +2 -1
- package/dist/docs/guides/caching.md +32 -1
- package/dist/docs/guides/database.md +2 -0
- package/dist/docs/guides/feature-matrix.md +58 -0
- package/dist/docs/guides/migrations.md +23 -2
- package/dist/docs/guides/which-api.md +2 -2
- package/dist/docs/index.md +3 -1
- package/dist/docs/skills/SKILL.md +1 -1
- package/dist/docs/skills/api-surface.md +5 -0
- package/dist/docs/skills/tasks-internals.md +4 -3
- package/dist/docs/skills/what-not-to-invent.md +4 -3
- package/dist/index.cjs +99 -30
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +204 -3
- package/dist/index.d.ts +204 -3
- package/dist/index.js +76 -7
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-FW42SBSM.js +14 -0
- package/dist/pgboss-backend-RVHUBJTU.cjs +14 -0
- package/dist/{pgboss-backend-DSO3QTNK.cjs.map → pgboss-backend-RVHUBJTU.cjs.map} +1 -1
- package/dist/registry/index.json +13 -1
- package/dist/registry/js-mongo/auth.json +1 -1
- package/dist/registry/js-mongo/forgot-password.json +1 -1
- package/dist/registry/js-mongo-collection/_base.json +1 -0
- package/dist/registry/js-mongo-collection/account-security.json +1 -0
- package/dist/registry/js-mongo-collection/account-settings.json +1 -0
- package/dist/registry/js-mongo-collection/admin-admins.json +1 -0
- package/dist/registry/js-mongo-collection/admin-analytics.json +1 -0
- package/dist/registry/js-mongo-collection/admin-billing.json +1 -0
- package/dist/registry/js-mongo-collection/admin-content.json +1 -0
- package/dist/registry/js-mongo-collection/admin-logs.json +1 -0
- package/dist/registry/js-mongo-collection/admin-support.json +1 -0
- package/dist/registry/js-mongo-collection/admin-system.json +1 -0
- package/dist/registry/js-mongo-collection/admin-users.json +1 -0
- package/dist/registry/js-mongo-collection/admin.json +1 -0
- package/dist/registry/js-mongo-collection/auth.json +1 -0
- package/dist/registry/js-mongo-collection/auth@apple.json +1 -0
- package/dist/registry/js-mongo-collection/auth@google.json +1 -0
- package/dist/registry/js-mongo-collection/billing.json +1 -0
- package/dist/registry/js-mongo-collection/email-client.json +1 -0
- package/dist/registry/js-mongo-collection/email-verification.json +1 -0
- package/dist/registry/js-mongo-collection/files.json +1 -0
- package/dist/registry/js-mongo-collection/forgot-password.json +1 -0
- package/dist/registry/js-mongo-collection/notifications.json +1 -0
- package/dist/registry/js-mongo-collection/support.json +1 -0
- package/dist/registry/js-mongo-collection/user-profile.json +1 -0
- package/dist/registry/js-pg-model/auth.json +1 -1
- package/dist/registry/js-pg-model/forgot-password.json +1 -1
- package/dist/registry/js-pg-table/auth.json +1 -1
- package/dist/registry/js-pg-table/forgot-password.json +1 -1
- package/dist/registry/ts-mongo/auth.json +1 -1
- package/dist/registry/ts-mongo/forgot-password.json +1 -1
- package/dist/registry/ts-mongo-collection/_base.json +1 -0
- package/dist/registry/ts-mongo-collection/account-security.json +1 -0
- package/dist/registry/ts-mongo-collection/account-settings.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-admins.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-analytics.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-billing.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-content.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-logs.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-support.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-system.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-users.json +1 -0
- package/dist/registry/ts-mongo-collection/admin.json +1 -0
- package/dist/registry/ts-mongo-collection/auth.json +1 -0
- package/dist/registry/ts-mongo-collection/auth@apple.json +1 -0
- package/dist/registry/ts-mongo-collection/auth@google.json +1 -0
- package/dist/registry/ts-mongo-collection/billing.json +1 -0
- package/dist/registry/ts-mongo-collection/email-client.json +1 -0
- package/dist/registry/ts-mongo-collection/email-verification.json +1 -0
- package/dist/registry/ts-mongo-collection/files.json +1 -0
- package/dist/registry/ts-mongo-collection/forgot-password.json +1 -0
- package/dist/registry/ts-mongo-collection/notifications.json +1 -0
- package/dist/registry/ts-mongo-collection/support.json +1 -0
- package/dist/registry/ts-mongo-collection/user-profile.json +1 -0
- package/dist/registry/ts-pg-model/auth.json +1 -1
- package/dist/registry/ts-pg-model/forgot-password.json +1 -1
- package/dist/registry/ts-pg-table/auth.json +1 -1
- package/dist/registry/ts-pg-table/forgot-password.json +1 -1
- package/dist/tasks/index.cjs +4 -2
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +4 -2
- package/dist/tasks/index.d.ts +4 -2
- package/dist/tasks/index.js +3 -1
- package/dist/thread-runner.cjs +8 -0
- package/dist/thread-runner.cjs.map +1 -0
- package/dist/thread-runner.d.cts +3 -0
- package/dist/thread-runner.d.ts +3 -0
- package/dist/thread-runner.js +8 -0
- package/dist/thread-runner.js.map +1 -0
- package/dist/{types-DAsBKVM-.d.cts → types-Bnxvj3l0.d.cts} +7 -1
- package/dist/{types-DAsBKVM-.d.ts → types-Bnxvj3l0.d.ts} +7 -1
- package/package.json +1 -1
- package/dist/chunk-2SETEVMO.js.map +0 -1
- package/dist/chunk-7YEX4MQV.cjs.map +0 -1
- package/dist/chunk-BBSZLGZW.js.map +0 -1
- package/dist/chunk-HBYSKULC.js.map +0 -1
- package/dist/chunk-LJNSJFOL.js +0 -38
- package/dist/chunk-LJNSJFOL.js.map +0 -1
- package/dist/chunk-OFA7OGN5.js.map +0 -1
- package/dist/chunk-QL6EWT4B.cjs.map +0 -1
- package/dist/chunk-RGT4ZVHL.cjs.map +0 -1
- package/dist/chunk-TI24L4XE.cjs.map +0 -1
- package/dist/chunk-TYCYYLLM.cjs.map +0 -1
- package/dist/chunk-ULWNHN6P.js.map +0 -1
- package/dist/chunk-VWSUQKCJ.cjs.map +0 -1
- package/dist/pgboss-backend-DSO3QTNK.cjs +0 -14
- package/dist/pgboss-backend-I6DFUNRM.js +0 -14
- /package/dist/{chunk-45BWAR6P.js.map → chunk-ATVD2HGC.js.map} +0 -0
- /package/dist/{chunk-7ZESZG3J.js.map → chunk-R4XO4SVM.js.map} +0 -0
- /package/dist/{pgboss-backend-I6DFUNRM.js.map → pgboss-backend-FW42SBSM.js.map} +0 -0
|
@@ -118,6 +118,49 @@ await Place.bulkWrite([
|
|
|
118
118
|
|
|
119
119
|
## Aggregation
|
|
120
120
|
|
|
121
|
+
### Typed pipelines
|
|
122
|
+
|
|
123
|
+
`pipeline()` builds an aggregation stage by stage, and each stage's output type is inferred from the schema — no hand-written result types:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
const ratings = await Place.pipeline()
|
|
127
|
+
.match({ owner: ownerId }) // string ids are cast, like find()
|
|
128
|
+
.unwind('$reviews') // reviews: { rating, text } (one per result)
|
|
129
|
+
.group({ _id: '$name', avg: { $avg: '$reviews.rating' }, n: { $sum: 1 } })
|
|
130
|
+
.sort({ avg: -1 });
|
|
131
|
+
// ratings: { _id: string; id: string; avg: number | null; n: number }[]
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
| Stage | Output type |
|
|
135
|
+
|---|---|
|
|
136
|
+
| `match(filter)`, `sort`, `skip`, `limit`, `sample(n)` | unchanged |
|
|
137
|
+
| `unwind('$field', { preserveNullAndEmptyArrays? })` | the array field holds one element (or `null` when preserved) |
|
|
138
|
+
| `group({ _id, …accumulators })` | `_id` (a `'$field'`, `null` or `{ key: '$field' }`), a string `id`, and per accumulator: `$sum`/`$count` → `number` (`$sum` of a `decimal128` → exact `string`), `$avg` → `number \| null`, `$min`/`$max`/`$first`/`$last` → the field's type, `$push`/`$addToSet` → an array of it |
|
|
139
|
+
| `project({ a: 1, b: 1 })` | only those fields, plus `id` |
|
|
140
|
+
| `count('n')` | `{ n: number }` (no result when nothing matched) |
|
|
141
|
+
| `lookup('ref', Model)` / `lookup({ from, localField, foreignField, as })` | see below |
|
|
142
|
+
| `addFields<{ x: number }>({ … })` | adds the fields you name in the generic |
|
|
143
|
+
| `stage<Out>({ … })` | anything else (`$facet`, `$bucket`, …), with its output type spelled out |
|
|
144
|
+
|
|
145
|
+
Field references (`'$name'`, `'$address.city'`) are checked against the record — one level into embedded objects. Await the builder, or call `.exec()`; `.toArray()` returns the stages as plain objects.
|
|
146
|
+
|
|
147
|
+
While the records still have the collection's shape, `match` and `sort` are cast like `find()` (`id` → `_id`, string ids → ObjectIds). After a stage that changes the shape (`group`, `unwind`, `lookup`, `project`, …) they're passed through as written.
|
|
148
|
+
|
|
149
|
+
### `lookup()`
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
const posts = await Post.lookup('author', User, { published: true });
|
|
153
|
+
// posts[0].author: User record | null (an array of refs → User records[])
|
|
154
|
+
|
|
155
|
+
const users = await User.pipeline()
|
|
156
|
+
.lookup({ from: Post, localField: 'id', foreignField: 'author', as: 'posts' });
|
|
157
|
+
// users[0].posts: Post records[]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The first form replaces a `ref` field with the record it points to (`null` when it points nowhere); the optional third argument filters first. Inside a pipeline it's `.lookup('author', User)`. The full form adds an array field; `id` means `_id` on either side. The target is a model, so the collection name is never spelled out.
|
|
161
|
+
|
|
162
|
+
### Raw pipelines
|
|
163
|
+
|
|
121
164
|
```ts
|
|
122
165
|
const ratings = await Place.aggregate<{ _id: string; avg: number }>([
|
|
123
166
|
{ $unwind: '$reviews' },
|
|
@@ -126,7 +169,7 @@ const ratings = await Place.aggregate<{ _id: string; avg: number }>([
|
|
|
126
169
|
]);
|
|
127
170
|
```
|
|
128
171
|
|
|
129
|
-
|
|
172
|
+
`aggregate()` passes the pipeline to MongoDB unchanged (no id casting); type the output with the generic. Results of both forms get the same conversions as records: decimals become strings, longs bigints, `_id` gains a string `id`.
|
|
130
173
|
|
|
131
174
|
## Change streams
|
|
132
175
|
|
|
@@ -90,6 +90,15 @@ ignite({ dashboard: true });
|
|
|
90
90
|
|
|
91
91
|
---
|
|
92
92
|
|
|
93
|
+
### `trustProxy`
|
|
94
|
+
|
|
95
|
+
Express's `trust proxy`. Set it when the app runs behind a proxy or load balancer (Render, Fly, Heroku, nginx, a cloud LB) so `req.ip` is the client, not the proxy: `true`, the number of hops (usually `1`), or addresses / subnets. Off by default, so `X-Forwarded-For` can't be spoofed. [`rateLimit`](../guides/caching.md#rate-limiting) keys on `req.ip`.
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
// efc.config.ts (scaffolded)
|
|
99
|
+
trustProxy: process.env.TRUST_PROXY ? Number(process.env.TRUST_PROXY) : undefined,
|
|
100
|
+
```
|
|
101
|
+
|
|
93
102
|
### `port`
|
|
94
103
|
|
|
95
104
|
HTTP listen port. Default: `3000`. `ignite()` never reads `PORT` from the environment itself — pass it explicitly, typically by reading `process.env.PORT` in `efc.config.ts` (see [Environment Variables](../guides/environment-variables.md)).
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Type inference
|
|
2
|
+
|
|
3
|
+
EFC models are typed from their schema literal — there's no interface to write or keep in step. All three model APIs (`defineModel`, `defineTable`, `defineCollection`) share the rules below; each also types its own queries.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { defineTable, type InferRecord, type InferCreate } from 'express-file-cluster';
|
|
7
|
+
|
|
8
|
+
export const Order = defineTable('Order', {
|
|
9
|
+
number: { type: 'string', required: true, unique: true },
|
|
10
|
+
status: { type: 'string', enum: ['open', 'paid'], default: 'open' },
|
|
11
|
+
total: { type: 'decimal', precision: 10, scale: 2, required: true },
|
|
12
|
+
lines: [{ sku: { type: 'string', required: true }, qty: { type: 'integer' } }],
|
|
13
|
+
paidAt: { type: 'date' },
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
type OrderRecord = InferRecord<typeof Order>;
|
|
17
|
+
// { id: string; number: string; status: 'open' | 'paid'; total: string;
|
|
18
|
+
// lines?: { sku: string; qty?: number }[]; paidAt?: Date; createdAt: Date; updatedAt: Date }
|
|
19
|
+
|
|
20
|
+
type NewOrder = InferCreate<typeof Order>;
|
|
21
|
+
// { number: string; total: string | number; status?: 'open' | 'paid'; lines?: …; paidAt?: Date | string | number }
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
| Helper | Gives you |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `InferRecord<typeof M>` | What reads return: every stored field, `id`, timestamps |
|
|
27
|
+
| `InferCreate<typeof M>` | What `create()` accepts |
|
|
28
|
+
| `InferTableRecord<typeof M>` | Same as `InferRecord`, for `defineTable` models (kept for older code) |
|
|
29
|
+
|
|
30
|
+
## Field types
|
|
31
|
+
|
|
32
|
+
| Schema `type` | Record type | `create()` / update input | `defineModel` | `defineTable` | `defineCollection` |
|
|
33
|
+
|---|---|---|:-:|:-:|:-:|
|
|
34
|
+
| `'string'` | `string` | `string` | ✓ | ✓ | ✓ |
|
|
35
|
+
| `'number'` | `number` | `number` | ✓ | ✓ | ✓ |
|
|
36
|
+
| `'boolean'` | `boolean` | `boolean` | ✓ | ✓ | ✓ |
|
|
37
|
+
| `'date'` | `Date` | `Date \| string \| number` | ✓ | ✓ | ✓ |
|
|
38
|
+
| `'objectId'` | `string` | `string` | ✓ | ✓ | ✓ |
|
|
39
|
+
| `'integer'` | `number` (whole, 32-bit) | `number` | | ✓ | |
|
|
40
|
+
| `'bigint'` | `bigint` | `bigint \| number` | | ✓ | |
|
|
41
|
+
| `'decimal'` | `string` (exact) | `string \| number` | | ✓ | |
|
|
42
|
+
| `'uuid'` | `string` | `string` | | ✓ | |
|
|
43
|
+
| `'json'` | `unknown` | `unknown` | | ✓ | |
|
|
44
|
+
| `'decimal128'` | `string` (exact) | `string \| number` | | | ✓ |
|
|
45
|
+
| `'long'` | `bigint` | `bigint \| number` | | | ✓ |
|
|
46
|
+
| `'geoPoint'` | `{ type: 'Point'; coordinates: [number, number] }` | same | | | ✓ |
|
|
47
|
+
| `'binary'` | `Buffer` | `Buffer` | | | ✓ |
|
|
48
|
+
| `enum: [...]` | union of the literals | same | ✓ | ✓ | ✓ |
|
|
49
|
+
| `{ type: 'array', of: X }` | `X[]` | `X[]` (input form of `X`) | ✓ | ✓ | ✓ |
|
|
50
|
+
| `[{ …schema }]` / `of: { …schema }` | array of the inferred object | same | ✓ | ✓ | ✓ |
|
|
51
|
+
| nested schema / `{ type: 'object', fields }` | the inferred object | same, with create rules | ✓ | ✓ | ✓ |
|
|
52
|
+
| `{ type: 'object' }` without `fields`, `{ type: 'array' }` without `of` | `unknown` / `unknown[]` | same | ✓ | ✓ | ✓ |
|
|
53
|
+
|
|
54
|
+
A type that isn't valid for the API (`'decimal128'` in `defineTable`, `'integer'` in `defineCollection`) is a compile error, and throws at definition time in JavaScript.
|
|
55
|
+
|
|
56
|
+
## Optional or not
|
|
57
|
+
|
|
58
|
+
| The field has | Record | `create()` input |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `required: true` | present | mandatory |
|
|
61
|
+
| `required: true` + `default` (or `sequence`) | present | optional |
|
|
62
|
+
| `default` or `sequence` only | present | optional |
|
|
63
|
+
| none of these | optional (`?`) | optional |
|
|
64
|
+
|
|
65
|
+
The rules apply inside embedded objects too; an embedded object's inner `required` fields only apply when the object is there.
|
|
66
|
+
|
|
67
|
+
## Ids and timestamps
|
|
68
|
+
|
|
69
|
+
| | `id` |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `defineModel`, `defineCollection` | `string` |
|
|
72
|
+
| `defineTable` | `string` (uuid, default) · `number` with `{ id: 'serial' }` · `bigint` with `{ id: 'bigserial' }` |
|
|
73
|
+
|
|
74
|
+
`createdAt` / `updatedAt: Date` are added unless `options.timestamps` is `false`; `{ createdAt: 'created_at', updatedAt: false }` renames or drops one, and the type follows.
|
|
75
|
+
|
|
76
|
+
## Typed queries
|
|
77
|
+
|
|
78
|
+
- **Filters, updates, sorts and `distinct()`** take the record's fields only; an undeclared field or a value outside an `enum` is a compile error.
|
|
79
|
+
- **`defineTable` `select` / `omit`** narrow the result type to those fields. **`include`** types the related records once the models are registered:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
declare module 'express-file-cluster' {
|
|
83
|
+
interface Tables { User: typeof User; Post: typeof Post }
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Apps from `create-efc-app` (and `efc db pull`) write this in `src/model/index.ts`. See [`defineTable` relations](./table.md).
|
|
88
|
+
- **`defineCollection` `pipeline()`** types every stage's output — `group` accumulators, `unwind`, `lookup`, `project`, `count` — and `lookup('ref', Model)` replaces a ref with the referenced record type. See [typed pipelines](./collection.md#typed-pipelines).
|
|
89
|
+
|
|
90
|
+
## When there's nothing to infer from
|
|
91
|
+
|
|
92
|
+
A schema stored in a variable annotated with the wide type has lost its literal:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
const schema: ModelSchema = { title: { type: 'string' } }; // ✗ InferRecord is a loose object
|
|
96
|
+
const schema = { title: { type: 'string' } } as const satisfies ModelSchema; // ✓
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Declare it inline (or `as const satisfies …`). `defineModel<T>('Name', schema)` with an explicit interface still works and keeps the v0.4 behaviour (`create()` takes `Partial<T>`).
|
package/dist/docs/cli/add.md
CHANGED
package/dist/docs/cli/db.md
CHANGED
|
@@ -8,11 +8,11 @@ efc db generate --verify # fail if the migrations miss anything the models
|
|
|
8
8
|
efc db sync [--dry-run] # reconcile tables/collections + indexes with src/model(s)/
|
|
9
9
|
efc db sync --dry-run --exit-code # exit 2 when the database has drifted from the models
|
|
10
10
|
efc db migrate [--baseline] # run pending migrations (one new batch); --baseline only records them
|
|
11
|
-
efc db pull [--out src/model] # write
|
|
11
|
+
efc db pull [--out src/model] [--sample 1000] # write models for the database: defineTable (PostgreSQL) / defineCollection (MongoDB)
|
|
12
12
|
efc db rollback [--steps 2] # revert the last batch(es)
|
|
13
13
|
efc db status # applied vs pending
|
|
14
14
|
efc db seed [name] # run all seeds, or one
|
|
15
|
-
efc db studio [--port 4983]
|
|
15
|
+
efc db studio [--port 4983] [--write] # browser on 127.0.0.1 (rows + structure); --write edits through src/model
|
|
16
16
|
```
|
|
17
17
|
|
|
18
18
|
## Common options
|
|
@@ -44,7 +44,7 @@ Pass `{ thread: true }` as the first argument. The handler runs in a dedicated `
|
|
|
44
44
|
|
|
45
45
|
```ts
|
|
46
46
|
// src/tasks/ResizeImage.ts
|
|
47
|
-
import { defineTask } from 'express-file-cluster/tasks';
|
|
47
|
+
import { defineTask, enqueue } from 'express-file-cluster/tasks';
|
|
48
48
|
import sharp from 'sharp';
|
|
49
49
|
|
|
50
50
|
interface ResizePayload {
|
|
@@ -58,10 +58,13 @@ export default defineTask<ResizePayload>(
|
|
|
58
58
|
const input = await downloadFromStorage(key);
|
|
59
59
|
const out = await sharp(input).resize(width).toBuffer();
|
|
60
60
|
await uploadToStorage(`${key}@${width}`, out);
|
|
61
|
+
await enqueue('NotifyUploaded', { key, width }); // works from a thread too
|
|
61
62
|
},
|
|
62
63
|
);
|
|
63
64
|
```
|
|
64
65
|
|
|
66
|
+
`enqueue()` works inside a thread task: the call is forwarded to the main thread, which owns the queue, and resolves (or rejects with the same error) once the job is queued — so a CPU-heavy step can hand off to the next one. The thread is a fresh module scope: open its own clients (database, storage) if it needs them, and don't rely on state from the main thread. The task module's `default` export must be the `defineTask(...)` result.
|
|
67
|
+
|
|
65
68
|
---
|
|
66
69
|
|
|
67
70
|
## Task options
|
|
@@ -210,8 +213,8 @@ The backend is inferred — BullMQ when `REDIS_URL` is set, pg-boss for a `postg
|
|
|
210
213
|
|
|
211
214
|
`packages/core/src/tasks/thread-runner.ts` is a dual-purpose module:
|
|
212
215
|
|
|
213
|
-
- **Worker-thread side** — when loaded inside a `worker_threads` worker
|
|
214
|
-
- **Main-thread side** — exports `runInThread(handlerPath, payload)` which spawns a `new Worker(thread-runner.js, { workerData })` and returns a `Promise<void>` that resolves on `
|
|
216
|
+
- **Worker-thread side** — when loaded inside a `worker_threads` worker (`workerData.efcTask`), imports the task file, calls `def.handler(payload)`, and posts `{ type: 'done', ok }` back. `enqueue()` in the thread posts `{ type: 'enqueue', id, name, payload }` and waits for `{ type: 'enqueued', id, error? }`; the port only keeps the thread alive while such a call is waiting, so a finished task's thread exits.
|
|
217
|
+
- **Main-thread side** — exports `runInThread(handlerPath, payload)` which spawns a `new Worker(thread-runner.js, { workerData })`, answers `enqueue` messages with the real `enqueue()`, and returns a `Promise<void>` that resolves on `done` / rejects on error. The build emits `dist/thread-runner.js` as its own file because the worker loads it by path.
|
|
215
218
|
|
|
216
219
|
---
|
|
217
220
|
|
|
@@ -20,7 +20,8 @@ The interactive wizard asks for the **base** app, then offers features:
|
|
|
20
20
|
? Project name: my-api
|
|
21
21
|
? Language: TypeScript | JavaScript
|
|
22
22
|
? Database: MongoDB | PostgreSQL
|
|
23
|
-
? Models: defineTable | defineModel (PostgreSQL
|
|
23
|
+
? Models: defineTable | defineModel (PostgreSQL)
|
|
24
|
+
defineCollection | defineModel (MongoDB)
|
|
24
25
|
? Task queue backend: pg-boss | BullMQ (BullMQ on MongoDB)
|
|
25
26
|
? Multi-core clustering? Yes
|
|
26
27
|
? Add features now? (none by default — or add any later with `efc add`)
|
|
@@ -41,13 +41,44 @@ await cache.clear('user:'); // every key with this pref
|
|
|
41
41
|
|
|
42
42
|
// Get-or-compute: concurrent callers in one process share a single computation
|
|
43
43
|
const stats = await cache.wrap('stats:daily', 60, () => Stats.aggregate(pipeline));
|
|
44
|
+
|
|
45
|
+
// Atomic counter — one count across every worker (and, on Redis, every instance)
|
|
46
|
+
const n = await cache.incr('signups:today', { ttl: 86_400 }); // TTL set when the key is created
|
|
44
47
|
```
|
|
45
48
|
|
|
46
49
|
Values are stored as JSON — `Date`s come back as ISO strings. `undefined` is never cached.
|
|
47
50
|
|
|
48
51
|
### When Redis is down
|
|
49
52
|
|
|
50
|
-
The cache **degrades instead of failing**: `get` returns `undefined`, `set`/`del` are no-ops, `wrap` just runs your function. Requests keep working (only slower), and a warning is logged at most every 30 seconds. Boot waits up to ~2 s for the first connection, then continues regardless.
|
|
53
|
+
The cache **degrades instead of failing**: `get` returns `undefined`, `set`/`del` are no-ops, `wrap` just runs your function, `incr` returns `undefined` (a count can't be made up). Requests keep working (only slower), and a warning is logged at most every 30 seconds. Boot waits up to ~2 s for the first connection, then continues regardless.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Rate limiting
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
import { rateLimit } from 'express-file-cluster';
|
|
61
|
+
|
|
62
|
+
// src/api/auth/login.ts
|
|
63
|
+
export const middlewares = [rateLimit({ window: '15m', max: 10 })];
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`rateLimit` counts in the cache (`cache.incr`), so the limit is one limit for the whole app — an in-memory counter per worker would let 8 workers accept 8 × `max`. With the `memory` backend that's per machine; use `redis` when you run several instances.
|
|
67
|
+
|
|
68
|
+
| Option | Default | |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| `window` | — | Seconds, or `'30s'` / `'15m'` / `'1h'` / `'1d'`. Windows are aligned to the clock. |
|
|
71
|
+
| `max` | — | Requests per window and key. The next one gets **429** with `Retry-After`. |
|
|
72
|
+
| `key` | client IP (`req.ip`) | Who a request counts against; return `undefined` to not limit it. |
|
|
73
|
+
| `name` | the route pattern | Routes with the same `name` share a limit. |
|
|
74
|
+
| `onCacheError` | `'allow'` | Cache unreachable: let requests through, or `'reject'` with 503. |
|
|
75
|
+
| `headers` | `true` | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. |
|
|
76
|
+
|
|
77
|
+
**Behind a proxy or load balancer, set `trustProxy` in `ignite()`** (`TRUST_PROXY=1` in scaffolded apps). Otherwise `req.ip` is the proxy's for every client, and an IP-keyed limit is one limit for everyone. The login and forgot-password routes `create-efc-app` generates key on the email too (`10 / 15 min per address + account`, `5 reset emails / hour per address`), so even then they limit one account, never everyone:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
rateLimit({ window: '15m', max: 10, key: (req) => `${req.ip}:${String(req.body?.email ?? '').toLowerCase()}` })
|
|
81
|
+
```
|
|
51
82
|
|
|
52
83
|
---
|
|
53
84
|
|
|
@@ -125,6 +125,8 @@ if (typeof refreshToken !== 'string') return res.status(400).json({ error: 'Inva
|
|
|
125
125
|
const user = await User.findOne({ refreshToken });
|
|
126
126
|
```
|
|
127
127
|
|
|
128
|
+
Without the check, `{"refreshToken": {"$ne": null}}` (or `{"not": ""}` on `defineTable`) matches any account that has a token — the account takeover fixed in the generated routes in 0.9.6 ([GHSA-85c7-prvr-q2rp](https://github.com/pr4shxnt/efc.js/security/advisories/GHSA-85c7-prvr-q2rp)).
|
|
129
|
+
|
|
128
130
|
— or validate the body with `export const schema` ([validation](./validation.md)), which replaces it with the parsed, typed output.
|
|
129
131
|
|
|
130
132
|
## Writing
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Feature matrix
|
|
2
|
+
|
|
3
|
+
What each model API does on which engine — and the test that proves it. Every test named here runs against a real database in CI; a test (`feature-matrix.test.ts`) fails if a cited test is renamed or removed, so this page can't quietly go stale.
|
|
4
|
+
|
|
5
|
+
✓ supported · — not available (by design: each native API speaks its engine's vocabulary — see [Which API?](./which-api.md))
|
|
6
|
+
|
|
7
|
+
## Models and validation
|
|
8
|
+
|
|
9
|
+
| Feature | `defineModel` MongoDB | `defineModel` PostgreSQL | `defineTable` | `defineCollection` | Proven by |
|
|
10
|
+
|---|:-:|:-:|:-:|:-:|---|
|
|
11
|
+
| Types inferred from the schema | ✓ | ✓ | ✓ | ✓ | `types/docs-types.test-d.ts: type-checked by tsc` |
|
|
12
|
+
| Validation on create and update → 400 | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: validates fields, embedded objects and array items` · `db/table.integration.test.ts: validates on create` · `db/collection.integration.test.ts: validates on create and on updates` |
|
|
13
|
+
| Unique violations → 409 | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: rejects duplicates of a unique field with 409` · `db/table.integration.test.ts: rejects duplicates with 409` |
|
|
14
|
+
| Defaults, `$now` / `$uuid` / sequences | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: creates records with defaults, sequences` · `db/model.smoke.test.ts: resolves $now / $uuid default operator codes` |
|
|
15
|
+
| Embedded objects and arrays | ✓ | ✓ (jsonb) | ✓ (jsonb) | ✓ | `db/engines.integration.test.ts: returns dates nested in objects and arrays as Date on both engines` |
|
|
16
|
+
| Undeclared fields ignored | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: ignores undeclared fields on writes` · `db/table.integration.test.ts: AND / OR / NOT combine, undefined is ignored, undeclared fields match nothing` |
|
|
17
|
+
| Engine guard (wrong engine fails clearly) | — | — | ✓ | ✓ | `db/engines.integration.test.ts: engine-native models refuse to run on the other engine` · `db/collection.integration.test.ts: rejects SQL-only types and PostgreSQL connections` |
|
|
18
|
+
| SQL types: integer, bigint, decimal, uuid, varchar, arrays, enums | — | — | ✓ | — | `db/table.integration.test.ts: creates SQL-native columns` · `db/table.integration.test.ts: create returns typed values` |
|
|
19
|
+
| BSON types: decimal128, long, binary, geoPoint | — | — | — | ✓ | `db/collection.integration.test.ts: round-trips BSON types` |
|
|
20
|
+
|
|
21
|
+
## Queries
|
|
22
|
+
|
|
23
|
+
| Feature | `defineModel` MongoDB | `defineModel` PostgreSQL | `defineTable` | `defineCollection` | Proven by |
|
|
24
|
+
|---|:-:|:-:|:-:|:-:|---|
|
|
25
|
+
| Filter operators, dotted paths, `$or`, `$exists` | ✓ | ✓ | — | ✓ | `db/engines.integration.test.ts: filters with operators, dotted paths, array containment` |
|
|
26
|
+
| Prisma-style `where` (incl. `mode: 'insensitive'`) | — | — | ✓ | — | `db/table.integration.test.ts: scalar filters: equals, not, in/notIn, ranges, strings, mode insensitive` |
|
|
27
|
+
| Sort, limit, skip, select / projection | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: supports sort, limit, skip and select` · `db/table.integration.test.ts: orderBy (multi-key, nulls), select, omit and distinct` · `db/collection.integration.test.ts: find with projection, sort, skip, limit` |
|
|
28
|
+
| Cursor pagination | — | — | ✓ | — | `db/table.integration.test.ts: cursor: walks every row exactly once` |
|
|
29
|
+
| `exists`, `distinct`, `updateOne`, `deleteOne`, `upsert` | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: upsert() creates, then updates, and survives concurrent calls` · `db/table.integration.test.ts: upsert is one INSERT … ON CONFLICT` |
|
|
30
|
+
| `aggregate` / `groupBy` | ✓ (pipeline) | — | ✓ | ✓ | `db/table.integration.test.ts: groupBy with aggregates, having, orderBy and take` · `db/collection.integration.test.ts: aggregate pipelines and populate` |
|
|
31
|
+
| Typed aggregation pipeline + `lookup()` | — | — | — | ✓ | `db/collection.integration.test.ts: typed pipeline: match (ids cast)` · `db/collection.integration.test.ts: lookup: a ref becomes its record` |
|
|
32
|
+
| Geo (`$near`) and `$text` | — | — | — | ✓ | `db/collection.integration.test.ts: find with projection, sort, skip, limit; geo $near; $text` |
|
|
33
|
+
| `bulkWrite`, change streams (`watch`) | — | — | — | ✓ | `db/collection.integration.test.ts: bulkWrite` · `db/collection.integration.test.ts: watch streams changes` |
|
|
34
|
+
| `findOneAndUpdate` (before / after / upsert) | — | — | — | ✓ | `db/collection.integration.test.ts: updates: results, findOneAndUpdate` |
|
|
35
|
+
|
|
36
|
+
## Relations
|
|
37
|
+
|
|
38
|
+
| Feature | `defineModel` MongoDB | `defineModel` PostgreSQL | `defineTable` | `defineCollection` | Proven by |
|
|
39
|
+
|---|:-:|:-:|:-:|:-:|---|
|
|
40
|
+
| `ref` + `populate` | ✓ | ✓ (plain column) | — | ✓ | `db/engines.integration.test.ts: populates single and array refs` |
|
|
41
|
+
| Real foreign keys (`onDelete` restrict / cascade / setNull) | — | — | ✓ | — | `db/table-relations.integration.test.ts: cascade deletes, setNull clears, restrict refuses with a 409` |
|
|
42
|
+
| Many-to-many join tables | — | — | ✓ | — | `db/table-m2n.integration.test.ts: stores the relation in a join table` |
|
|
43
|
+
| `include` in one SQL statement, any depth | — | — | ✓ | — | `db/table-include.integration.test.ts: nests includes with where, orderBy, take, skip — in one statement` |
|
|
44
|
+
| Relation filters (`some` / `every` / `none`, `is` / `isNot`) | — | — | ✓ | — | `db/table-nested.integration.test.ts: some / none / every on a hasMany back-relation` |
|
|
45
|
+
| Nested writes (`connect`, `create`, `connectOrCreate`, …) | — | — | ✓ | — | `db/table-nested.integration.test.ts: creates with connect, create and connectOrCreate` |
|
|
46
|
+
|
|
47
|
+
## Transactions, schema and tooling
|
|
48
|
+
|
|
49
|
+
| Feature | `defineModel` MongoDB | `defineModel` PostgreSQL | `defineTable` | `defineCollection` | Proven by |
|
|
50
|
+
|---|:-:|:-:|:-:|:-:|---|
|
|
51
|
+
| `transaction()` | ✓ (replica set) | ✓ | ✓ | ✓ (replica set) | `db/table.integration.test.ts: joins transaction() and rolls back` · `db/collection.integration.test.ts: joins transactions` |
|
|
52
|
+
| Auto-sync on first use (never drops data) | ✓ | ✓ | ✓ | ✓ | `db/engines.integration.test.ts: works on first use — no sync() or migration needed` · `db/engines.integration.test.ts: evolving a model never strands writes or rows` |
|
|
53
|
+
| `efc db generate` migrations from model diffs | ✓ | ✓ | ✓ | ✓ | `integration/db-generate.test.ts: writes a migration from the models, verifies it` · `integration/db-generate.test.ts: creates collections and indexes` |
|
|
54
|
+
| `efc db pull` | — | ✓ (as defineTable) | ✓ | ✓ | `integration/db-generate.test.ts: import-prisma → generate → migrate → pull round-trips` · `db/pull-mongo.integration.test.ts: the pulled models read the data and find nothing to sync` |
|
|
55
|
+
| `efc import-prisma` | — | — | ✓ | — | `db/prisma-import.test.ts: maps scalars, ids, timestamps, defaults` |
|
|
56
|
+
| Query logging + N+1 warnings | ✓ | ✓ | ✓ | ✓ | `db/query-log.integration.test.ts: warns once per request about an N+1 pattern` |
|
|
57
|
+
| `efc db studio --write` (through the model) | ✓ | ✓ | ✓ | ✓ | `db/studio.integration.test.ts: inserts, edits and deletes through the model` · `db/studio.integration.test.ts: writes through defineCollection` |
|
|
58
|
+
| Same table from `defineModel` and `defineTable` | — | ✓ | ✓ | — | `db/table.integration.test.ts: defineModel and defineTable over the same table` |
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
| `efc db status` | Lists applied (with batch) and pending migrations |
|
|
11
11
|
| `efc db seed [name]` | Runs every seed in `src/seeds/`, or just one |
|
|
12
12
|
| `efc db sync [--dry-run] [--exit-code]` | Brings the database in line with the models (or reports what would change) |
|
|
13
|
-
| `efc db pull` | Writes `defineTable` models for an existing PostgreSQL database |
|
|
14
|
-
| `efc db studio [-p 4983]` | Opens a
|
|
13
|
+
| `efc db pull` | Writes `defineTable` models for an existing PostgreSQL database, `defineCollection` models for a MongoDB one |
|
|
14
|
+
| `efc db studio [-p 4983] [--write]` | Opens a database browser on `127.0.0.1` — read-only unless `--write` |
|
|
15
15
|
|
|
16
16
|
All of them read `DATABASE_URL` from the environment or `.env` (override with `--database-url`); the engine follows the URL scheme.
|
|
17
17
|
|
|
@@ -119,6 +119,23 @@ efc db pull --out pulled # somewhere else, to compare
|
|
|
119
119
|
|
|
120
120
|
A schema EFC created pulls back to models that sync finds nothing to change in. For a schema EFC didn't create, anything that has no EFC equivalent is noted at the top of the file: expression or partial indexes, other CHECKs, composite keys, and other defaults. Existing files are kept unless you pass `--force`.
|
|
121
121
|
|
|
122
|
+
## Pulling an existing database (MongoDB)
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
efc db pull # → src/model/<Model>.ts + index.ts (defineCollection)
|
|
126
|
+
efc db pull --sample 5000 # sample more documents per collection (default 1000)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
MongoDB has no schema to read, so `pull` samples each collection (`$sample`) and infers one from the documents:
|
|
130
|
+
|
|
131
|
+
- **Types:** `string`, `number`, `boolean`, `date`, `objectId`, `decimal128`, `long`, `binary` and GeoJSON points (`geoPoint`); embedded objects become nested schemas, arrays of objects `[{ … }]`, other arrays `{ type: 'array', of }`.
|
|
132
|
+
- **Required:** only when every sampled document had a non-null value. A field with mixed types (or only nulls) becomes `{ type: 'object' }` (any value) with a note.
|
|
133
|
+
- **Refs:** an `objectId` field gets `ref` when its name matches another collection (`owner`, `ownerId` → `Owner`) or when every sampled id exists in exactly one other collection; otherwise a note asks you to add it.
|
|
134
|
+
- **Indexes:** single-field unique, plain, `text`, `2dsphere` and `hashed` indexes go on the field; compound, partial and TTL indexes into `indexes`.
|
|
135
|
+
- **Names and timestamps:** a model per collection (`audit_log` → `AuditLog`, with `collection: 'audit_log'` when mongoose wouldn't pick that name); `createdAt`/`updatedAt` dates map to the default `timestamps`, otherwise `timestamps: false`.
|
|
136
|
+
|
|
137
|
+
`_id` and `__v` are left to defineCollection. Read the generated files before using them: a sample shows what the data *has*, not what it must have.
|
|
138
|
+
|
|
122
139
|
`required` and `default` live in the model, not the database. A table created by `sync` or a migration without `--tighten` has nullable columns and no defaults, so its fields pull back as optional. Generate with `--tighten` if you want `required` enforced (and pulled back).
|
|
123
140
|
|
|
124
141
|
Coming from Prisma? See [Coming from Prisma](./coming-from-prisma.md).
|
|
@@ -215,3 +232,7 @@ CMD ["sh", "-c", "npx efc db migrate --dist && npx efc start prod"]
|
|
|
215
232
|
## Studio
|
|
216
233
|
|
|
217
234
|
`efc db studio` serves a read-only browser at `http://127.0.0.1:4983`: every table/collection with its row count, paginated rows, and expandable JSON cells. It binds to localhost only and rejects anything but `GET`.
|
|
235
|
+
|
|
236
|
+
`efc db studio --write` adds **Insert**, **edit** (✎) and **Delete**. Writes go through your models in `src/model`, so validation, defaults, casting and timestamps apply exactly as in your app; a validation error is shown next to the editor. Tables or collections that no model stores in stay read-only. Ids, `createdAt`/`updatedAt` and `__v` are never written from the editor.
|
|
237
|
+
|
|
238
|
+
Only the studio page can write: every write must carry a random token embedded in that page, come from the studio's own origin, and be JSON — so another site open in your browser can't reach it. Writes change real data; point `DATABASE_URL` at a development database.
|
|
@@ -8,12 +8,12 @@ EFC has three ways to define a model. They share one foundation: the schema form
|
|
|
8
8
|
| Queries | portable subset: `find(filter, { sort, limit, populate })`, `$set`, `$inc` | Prisma-style: `findMany({ where, include, orderBy, take, cursor })`, `findUnique`, `upsert`, `groupBy`, `aggregate` | mongoose-style: every query operator, `find(filter, { projection })`, `findOneAndUpdate`, `bulkWrite`, `aggregate(pipeline)`, `watch` |
|
|
9
9
|
| Relations | `ref` + `populate` (a plain column on PostgreSQL) | real foreign keys, many-to-many join tables, `include` in one SQL statement, relation filters, nested writes | `ref` + `populate`, `$lookup`, embedded documents |
|
|
10
10
|
| Field types | the portable set (`string`, `number`, `boolean`, `date`, `objectId`, objects, arrays) | + `integer`, `bigint`, `decimal`, `uuid`, `json`, `varchar`, native arrays and enums, `serial` ids | + `decimal128`, `long`, `geoPoint`, `binary`; `2dsphere`, `text`, `hashed` and partial indexes |
|
|
11
|
-
| Migrations | auto-sync, `efc db generate` | auto-sync, `efc db generate`, `efc db pull`, `efc import-prisma` | auto-sync, `efc db generate` |
|
|
11
|
+
| Migrations | auto-sync, `efc db generate` | auto-sync, `efc db generate`, `efc db pull`, `efc import-prisma` | auto-sync, `efc db generate`, `efc db pull` |
|
|
12
12
|
| Wrong engine | — | fails at first use with an `[EFC]` error naming the model | the same |
|
|
13
13
|
|
|
14
14
|
## Pick one
|
|
15
15
|
|
|
16
|
-
- **Building on PostgreSQL:** use `defineTable`. You get foreign keys, joins and SQL types. `create-efc-app` generates `defineTable` models for PostgreSQL apps.
|
|
16
|
+
- **Building on PostgreSQL:** use `defineTable`. You get foreign keys, joins and SQL types. `create-efc-app` generates `defineTable` models for PostgreSQL apps (and `defineCollection` for MongoDB apps).
|
|
17
17
|
- **Building on MongoDB:** use `defineCollection`. You get the full query language, geo and text search, BSON types, `bulkWrite` and change streams. It is mongoose underneath (`raw()` hands you the mongoose model).
|
|
18
18
|
- **The app may switch engines, or ships to both:** use `defineModel` and stay inside the shared filter and update subset (`$eq $ne $gt $gte $lt $lte $in $nin $exists $regex $and $or`; `$set $unset $inc $push $pull`).
|
|
19
19
|
- **Coming from Prisma:** use `defineTable`. `efc import-prisma` writes the models for you. See [Coming from Prisma](./coming-from-prisma.md).
|
package/dist/docs/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**express-file-cluster (EFC)** is an opinionated backend framework built on Express. It removes routing ceremony, saturates every CPU core automatically, and ships a production-grade background-task subsystem — all from a single `ignite()` call.
|
|
4
4
|
|
|
5
|
-
> **Status: v0.
|
|
5
|
+
> **Status: v0.10.0 — Beta.** File-based routing (incl. catch-all and optional segments), request validation, clustering, auth, structured logging, MongoDB and PostgreSQL models with types inferred from the schema, PostgreSQL-native `defineTable` (Prisma-style queries and relations: foreign keys, many-to-many, `include`, relation filters, nested writes), query logging, BullMQ and pg-boss tasks with cron and dead-letter tooling, migrations (written for you from model changes: `efc db generate`, plus `efc db pull` and `efc import-prisma`), and the `efc add` feature registry (auth, admin, billing… copied into your app as source you own) are all implemented.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -39,6 +39,8 @@
|
|
|
39
39
|
| [RBAC](./guides/rbac.md) | Role-based route protection via the `requireAuth('role')` shorthand |
|
|
40
40
|
| [Database](./guides/database.md) | `defineModel`, queries, transactions, MongoDB vs PostgreSQL |
|
|
41
41
|
| [Which model API?](./guides/which-api.md) | `defineModel` vs `defineTable` vs `defineCollection`, and moving between them |
|
|
42
|
+
| [Feature matrix](./guides/feature-matrix.md) | What each model API does on which engine, with the test that proves each row |
|
|
43
|
+
| [Type inference](./api-reference/types.md) | What every schema type becomes in records and inputs, ids, timestamps, typed queries |
|
|
42
44
|
| [Relations](./guides/relations.md) | Foreign keys, many-to-many, `include`, relation filters, nested writes |
|
|
43
45
|
| [defineTable](./api-reference/table.md) | PostgreSQL-native models: Prisma-style queries, SQL types, aggregation |
|
|
44
46
|
| [defineCollection](./api-reference/collection.md) | MongoDB-native models: mongoose-style queries, BSON types, geo, bulk writes, change streams |
|
|
@@ -37,7 +37,7 @@ Load **only** the module the work points to. Each is self-contained.
|
|
|
37
37
|
docs/ ← full documentation
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
## Status (v0.
|
|
40
|
+
## Status (v0.10.0 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
|
|
41
41
|
|
|
42
42
|
Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only cookie + Bearer token auth (scrypt password hashing built in), structured logging (pino, request IDs), `defineModel` on MongoDB (mongoose) **and** PostgreSQL (Drizzle) with validation, query options, bulk ops, transactions, `sync()`/`drop()`, PostgreSQL-native `defineTable` (Prisma-style queries, foreign keys, many-to-many, `include`, relation filters, nested writes), MongoDB-native `defineCollection` (mongoose vocabulary, BSON types, geo/text, `bulkWrite`, change streams), query logging (`logging.queries`), BullMQ **and** pg-boss task backends with cron schedules and dead-letter CLI, worker_threads for CPU-bound tasks, migrations/seeds/studio (`efc db`) incl. migrations generated from model diffs (`efc db generate`), `efc db pull` and `efc import-prisma`, full CLI.
|
|
43
43
|
|
|
@@ -81,6 +81,11 @@ const cache: {
|
|
|
81
81
|
clear(prefix?): Promise<number>;
|
|
82
82
|
}
|
|
83
83
|
function cacheResponse(ttl: number | { ttl; perUser?: boolean; key?: (req) => string }): RequestHandler
|
|
84
|
+
// Fixed window counted with cache.incr — one limit across workers (memory) / instances (redis).
|
|
85
|
+
// key defaults to req.ip: behind a proxy set ignite({ trustProxy }) or everyone shares one bucket.
|
|
86
|
+
function rateLimit(o: { window: number | '15m'; max: number; key?: (req) => string | undefined;
|
|
87
|
+
name?: string; message?: string; onCacheError?: 'allow' | 'reject'; headers?: boolean }): RequestHandler
|
|
88
|
+
// cache.incr(key, { ttl? }): Promise<number | undefined> — atomic; undefined when Redis is down
|
|
84
89
|
// GET/HEAD 200 JSON only; X-Cache: HIT|MISS; keys under 'res:' + originalUrl
|
|
85
90
|
|
|
86
91
|
function scanDir(dir: string, base?: string, maxDepth?: number): RouteEntry[]
|
|
@@ -99,9 +99,10 @@ enqueue('ResizeImage', payload)
|
|
|
99
99
|
```
|
|
100
100
|
|
|
101
101
|
`runInThread` in `thread-runner.ts`:
|
|
102
|
-
- Spawns `new Worker(thread-runner.js, { workerData: { handlerPath, payload } })`
|
|
103
|
-
- Worker-side: imports `handlerPath`, reads `mod.default`, calls `def.handler(payload)`
|
|
104
|
-
-
|
|
102
|
+
- Spawns `new Worker(thread-runner.js, { workerData: { efcTask: true, handlerPath, payload } })` — `dist/thread-runner.js` is its own tsup entry (loaded by path; before 0.10.0 it wasn't emitted and every thread task failed)
|
|
103
|
+
- Worker-side: imports `handlerPath`, reads `mod.default`, calls `def.handler(payload)`, posts `{ type: 'done', ok, error? }`
|
|
104
|
+
- `enqueue()` inside the thread goes through `globalThis[Symbol.for('efc.enqueueBridge')]` → `{ type: 'enqueue' }` message → main thread's real `enqueue()` → `{ type: 'enqueued', error? }`; the port is ref'd only while a call waits, so the thread still exits
|
|
105
|
+
- Tested against the built package: `integration/thread-tasks.test.ts`
|
|
105
106
|
|
|
106
107
|
`thread: true` requires `def.filePath` to be set. This is only guaranteed when the task was registered via `scanTasks` (which stores the file path). If you call `registerTask` manually without `filePath`, `thread: true` will silently fall through to the event loop (the `&&` short-circuits).
|
|
107
108
|
|
|
@@ -136,7 +136,7 @@ efc lint # NOT IMPLEMENTED
|
|
|
136
136
|
efc deploy # NOT IMPLEMENTED
|
|
137
137
|
efc db reset / fresh # NOT IMPLEMENTED
|
|
138
138
|
efc db push # NOT IMPLEMENTED — that's `efc db sync` (or autoSync)
|
|
139
|
-
efc db pull # PostgreSQL
|
|
139
|
+
efc db pull # PostgreSQL → defineTable; MongoDB → defineCollection inferred from sampled docs (--sample)
|
|
140
140
|
efc remove <item> # NOT IMPLEMENTED — `efc add` copies files; delete them yourself
|
|
141
141
|
efc add <url|@ns/x> # NOT IMPLEMENTED — only the built-in registry (efc list); no third-party registries
|
|
142
142
|
```
|
|
@@ -168,8 +168,9 @@ drift), `efc db migrate --baseline` (record as applied without running).
|
|
|
168
168
|
// ❌ Sync never DROPS columns, never adds NOT NULL and never deletes rows — that's
|
|
169
169
|
// `efc db generate <name> --allow-drop` / `--tighten` (explicit, reviewed migrations).
|
|
170
170
|
// Splits and backfills still need a hand-written migration (db.query()).
|
|
171
|
-
// ✅ `efc db generate` writes migrations from model diffs; `efc db pull`
|
|
172
|
-
//
|
|
171
|
+
// ✅ `efc db generate` writes migrations from model diffs; `efc db pull` writes defineTable
|
|
172
|
+
// (PostgreSQL) or defineCollection (MongoDB, from sampled documents) files, and
|
|
173
|
+
// `efc import-prisma` writes defineTable files.
|
|
173
174
|
// ❌ No joins in the model API — populate does a second query; for SQL joins use
|
|
174
175
|
// Drizzle via Model.raw() or db.query().
|
|
175
176
|
// ❌ aggregate() is MongoDB-only (rejects on PostgreSQL).
|