express-file-cluster 0.3.15 → 0.5.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-3VWD2ZED.js +60 -0
- package/dist/chunk-3VWD2ZED.js.map +1 -0
- package/dist/chunk-47K2532L.cjs +196 -0
- package/dist/chunk-47K2532L.cjs.map +1 -0
- package/dist/chunk-5PDAWMGF.js +438 -0
- package/dist/chunk-5PDAWMGF.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-ALBDM5R3.cjs +60 -0
- package/dist/chunk-ALBDM5R3.cjs.map +1 -0
- package/dist/chunk-JJJJTACK.js +196 -0
- package/dist/chunk-JJJJTACK.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-M7MUPWCE.js +116 -0
- package/dist/chunk-M7MUPWCE.js.map +1 -0
- package/dist/chunk-PMF4GMHD.js +154 -0
- package/dist/chunk-PMF4GMHD.js.map +1 -0
- package/dist/chunk-QTRGJ2EN.cjs +2635 -0
- package/dist/chunk-QTRGJ2EN.cjs.map +1 -0
- package/dist/chunk-RSBW2B3D.cjs +126 -0
- package/dist/chunk-RSBW2B3D.cjs.map +1 -0
- package/dist/chunk-RTFJ32T5.js +2635 -0
- package/dist/chunk-RTFJ32T5.js.map +1 -0
- package/dist/chunk-SFVEQ2T5.cjs +438 -0
- package/dist/chunk-SFVEQ2T5.cjs.map +1 -0
- package/dist/chunk-SZT36SGB.cjs +154 -0
- package/dist/chunk-SZT36SGB.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-ULQXD4YZ.cjs +116 -0
- package/dist/chunk-ULQXD4YZ.cjs.map +1 -0
- package/dist/chunk-VYHJX54R.js +126 -0
- package/dist/chunk-VYHJX54R.js.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 +323 -0
- package/dist/docs/api-reference/table.md +250 -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 +70 -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 +308 -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 +289 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +472 -7
- package/dist/index.d.ts +472 -7
- package/dist/index.js +283 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-3E6ATY42.cjs +14 -0
- package/dist/pgboss-backend-3E6ATY42.cjs.map +1 -0
- package/dist/pgboss-backend-UUJOVEYK.js +14 -0
- package/dist/pgboss-backend-UUJOVEYK.js.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-DJCPAsM4.d.cts +541 -0
- package/dist/types-DJCPAsM4.d.ts +541 -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,541 @@
|
|
|
1
|
+
import { RequestHandler, ErrorRequestHandler } from 'express';
|
|
2
|
+
|
|
3
|
+
type DatabaseEngine = 'mongodb' | 'postgresql';
|
|
4
|
+
type AuthStrategy = 'http-only' | 'localStorage';
|
|
5
|
+
type TaskBackend = 'bullmq' | 'pg-boss';
|
|
6
|
+
interface TaskConfig {
|
|
7
|
+
backend: TaskBackend;
|
|
8
|
+
/** BullMQ only. Default: redis://localhost:6379. */
|
|
9
|
+
redisUrl?: string;
|
|
10
|
+
/** pg-boss only. Default: `databaseUrl`. */
|
|
11
|
+
connectionString?: string;
|
|
12
|
+
/** pg-boss only: Postgres schema for its tables. Default: 'pgboss'. */
|
|
13
|
+
schema?: string;
|
|
14
|
+
concurrency?: number;
|
|
15
|
+
/** Max milliseconds `enqueue()` waits for Redis before rejecting. Default: 5000. */
|
|
16
|
+
enqueueTimeout?: number;
|
|
17
|
+
/**
|
|
18
|
+
* Queue name. Apps sharing one Redis database (or Postgres schema, for pg-boss) must
|
|
19
|
+
* use different names, or they will run each other's jobs. Default: 'efc'.
|
|
20
|
+
*/
|
|
21
|
+
queue?: string;
|
|
22
|
+
}
|
|
23
|
+
interface CacheCommon {
|
|
24
|
+
/** Key prefix, so apps can share one store. Default: 'efc:'. */
|
|
25
|
+
prefix?: string;
|
|
26
|
+
/**
|
|
27
|
+
* What `requireAuth` does when it can't reach the cache to check for revoked sessions:
|
|
28
|
+
* - `'reject'` (default): answer 503 — a revoked token can never slip through, at the
|
|
29
|
+
* cost of authenticated routes being unavailable during the outage.
|
|
30
|
+
* - `'allow'`: let the request through and log an error — availability first.
|
|
31
|
+
*/
|
|
32
|
+
onRevocationCheckError?: 'reject' | 'allow';
|
|
33
|
+
}
|
|
34
|
+
type CacheConfig = (CacheCommon & {
|
|
35
|
+
backend: 'redis';
|
|
36
|
+
/** Default: redis://localhost:6379. Supports rediss://, ACL users and /db. */
|
|
37
|
+
url?: string;
|
|
38
|
+
/** Per-command timeout in ms before treating Redis as unavailable. Default: 1000. */
|
|
39
|
+
timeout?: number;
|
|
40
|
+
}) | (CacheCommon & {
|
|
41
|
+
/**
|
|
42
|
+
* In-process store. Under clustering it lives in the primary and workers reach it
|
|
43
|
+
* over IPC, so all workers share it — but it is still one machine's memory: not
|
|
44
|
+
* shared across instances, and emptied on restart. Use Redis for multi-instance.
|
|
45
|
+
*/
|
|
46
|
+
backend: 'memory';
|
|
47
|
+
/** Least-recently-used entries are evicted beyond this. Default: 10 000. */
|
|
48
|
+
maxEntries?: number;
|
|
49
|
+
});
|
|
50
|
+
interface LoggingConfig {
|
|
51
|
+
/** Minimum level to emit. Default: 'info'. */
|
|
52
|
+
level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
|
|
53
|
+
/** Human-readable lines instead of JSON. Default: on in a non-production TTY. */
|
|
54
|
+
pretty?: boolean;
|
|
55
|
+
/** Log one line per completed request (method, url, status, duration). Default: true. */
|
|
56
|
+
requests?: boolean;
|
|
57
|
+
}
|
|
58
|
+
interface CorsConfig {
|
|
59
|
+
origin?: string | string[] | boolean;
|
|
60
|
+
methods?: string | string[];
|
|
61
|
+
allowedHeaders?: string | string[];
|
|
62
|
+
credentials?: boolean;
|
|
63
|
+
maxAge?: number;
|
|
64
|
+
}
|
|
65
|
+
interface EFCConfig {
|
|
66
|
+
port?: number;
|
|
67
|
+
basePath?: string;
|
|
68
|
+
dashboard?: boolean;
|
|
69
|
+
database?: DatabaseEngine;
|
|
70
|
+
databaseUrl?: string;
|
|
71
|
+
authStrategy?: AuthStrategy;
|
|
72
|
+
jwtSecret?: string;
|
|
73
|
+
/** JWT lifetime, e.g. '15m', '1h', '7d'. Default: '7d'. */
|
|
74
|
+
jwtExpiresIn?: string;
|
|
75
|
+
/** Cookie domain for the 'http-only' auth strategy. Default: unset (host-only cookie). */
|
|
76
|
+
cookieDomain?: string;
|
|
77
|
+
cluster?: boolean;
|
|
78
|
+
workers?: number;
|
|
79
|
+
tasks?: TaskConfig | false;
|
|
80
|
+
cors?: boolean | CorsConfig;
|
|
81
|
+
/**
|
|
82
|
+
* Key/value cache (`cache`, `cacheResponse`) — and the store `requireAuth` checks
|
|
83
|
+
* for revoked sessions (`revokeSession`, `revokeAllSessions`).
|
|
84
|
+
*/
|
|
85
|
+
cache?: CacheConfig | false;
|
|
86
|
+
/**
|
|
87
|
+
* Keep tables/collections and indexes in step with your models automatically, the
|
|
88
|
+
* first time each model is used in a process — like mongoose does for collections and
|
|
89
|
+
* indexes. Turn off to manage the schema only through migrations (`Model.sync()`,
|
|
90
|
+
* `efc db sync`). Default: true.
|
|
91
|
+
*/
|
|
92
|
+
autoSync?: boolean;
|
|
93
|
+
/** Structured logging (pino). `false` silences framework logs. */
|
|
94
|
+
logging?: LoggingConfig | false;
|
|
95
|
+
/** Request timeout in milliseconds. Requests exceeding this duration will be terminated with 408. */
|
|
96
|
+
requestTimeout?: number;
|
|
97
|
+
globalMiddlewares?: RequestHandler[];
|
|
98
|
+
onWorkerReady?: (id: number) => void;
|
|
99
|
+
onWorkerCrash?: (id: number, code: number) => void;
|
|
100
|
+
onError?: ErrorRequestHandler;
|
|
101
|
+
}
|
|
102
|
+
interface RouteEntry {
|
|
103
|
+
urlPath: string;
|
|
104
|
+
filePath: string;
|
|
105
|
+
params: string[];
|
|
106
|
+
/** Set for routes with a catch-all segment; captures map onto `params` in order. */
|
|
107
|
+
pattern?: RegExp;
|
|
108
|
+
}
|
|
109
|
+
interface RouteMethodMeta {
|
|
110
|
+
description?: string;
|
|
111
|
+
request?: {
|
|
112
|
+
headers?: Record<string, string>;
|
|
113
|
+
params?: Record<string, string>;
|
|
114
|
+
query?: Record<string, string>;
|
|
115
|
+
body?: unknown;
|
|
116
|
+
};
|
|
117
|
+
response?: {
|
|
118
|
+
status?: number;
|
|
119
|
+
body?: unknown;
|
|
120
|
+
};
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Keyed by HTTP method (`GET`, `POST`, ...) so each method implemented in a
|
|
124
|
+
* route file gets its own documentation block in the dashboard.
|
|
125
|
+
*/
|
|
126
|
+
type RouteMeta = Partial<Record<string, RouteMethodMeta>>;
|
|
127
|
+
/**
|
|
128
|
+
* Any Standard Schema validator (zod >=3.24, valibot, arktype, ...) or an object
|
|
129
|
+
* with a zod-style `safeParse`. EFC never imports a validation library itself.
|
|
130
|
+
*/
|
|
131
|
+
type Validator = {
|
|
132
|
+
readonly '~standard': {
|
|
133
|
+
validate: (value: unknown) => unknown;
|
|
134
|
+
};
|
|
135
|
+
} | {
|
|
136
|
+
safeParse: (value: unknown) => unknown;
|
|
137
|
+
};
|
|
138
|
+
/** Validators for each part of the request; every key is optional. */
|
|
139
|
+
interface RequestSchema {
|
|
140
|
+
params?: Validator;
|
|
141
|
+
query?: Validator;
|
|
142
|
+
body?: Validator;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* `export const schema` in a route file: either one `RequestSchema` applied to every
|
|
146
|
+
* method, or keyed by method (`{ POST: { body }, GET: { query } }`).
|
|
147
|
+
*/
|
|
148
|
+
type RouteSchema = RequestSchema | Partial<Record<string, RequestSchema>>;
|
|
149
|
+
interface ValidationIssue {
|
|
150
|
+
location: 'params' | 'query' | 'body';
|
|
151
|
+
/** Dot-joined path inside that location, e.g. `address.zip`; empty for the root. */
|
|
152
|
+
path: string;
|
|
153
|
+
message: string;
|
|
154
|
+
}
|
|
155
|
+
interface TaskOptions {
|
|
156
|
+
thread?: boolean;
|
|
157
|
+
retries?: number;
|
|
158
|
+
backoff?: 'fixed' | 'exponential';
|
|
159
|
+
concurrency?: number;
|
|
160
|
+
/**
|
|
161
|
+
* Cron pattern for recurring runs, e.g. `'0 3 * * *'` (daily 03:00). A 6-field
|
|
162
|
+
* pattern adds seconds. The handler receives `{}` as its payload on scheduled runs.
|
|
163
|
+
*/
|
|
164
|
+
schedule?: string;
|
|
165
|
+
/** IANA timezone for `schedule`, e.g. `'Europe/Berlin'`. Default: server local time. */
|
|
166
|
+
timezone?: string;
|
|
167
|
+
}
|
|
168
|
+
interface TaskDefinition<TPayload = unknown> {
|
|
169
|
+
handler: (payload: TPayload) => Promise<void>;
|
|
170
|
+
options: TaskOptions;
|
|
171
|
+
name: string;
|
|
172
|
+
filePath?: string;
|
|
173
|
+
}
|
|
174
|
+
/** Primitive field types usable directly, or as the item type of an `array` field via `of`. */
|
|
175
|
+
type PrimitiveFieldType = 'string' | 'number' | 'boolean' | 'date' | 'object' | 'objectId';
|
|
176
|
+
/**
|
|
177
|
+
* Sentinel default-value codes, resolved at schema-compile time to a generator
|
|
178
|
+
* function so each document gets a freshly-computed value (never baked in once
|
|
179
|
+
* at schema-definition time):
|
|
180
|
+
* - `'$now'` — the current `Date` (pair with `type: 'date'`)
|
|
181
|
+
* - `'$uuid'` — a fresh `crypto.randomUUID()` string (pair with `type: 'string'`)
|
|
182
|
+
* - `'$objectId'` — a fresh Mongoose `ObjectId` (pair with `type: 'objectId'`)
|
|
183
|
+
* - `'$timestamp'` — the current epoch milliseconds as a `number` (pair with `type: 'number'`)
|
|
184
|
+
* - `'$shortId'` — a random 16-character base64url string (pair with `type: 'string'`);
|
|
185
|
+
* a shorter, non-UUID-shaped alternative to `'$uuid'` for tokens/keys
|
|
186
|
+
* - `'$currentUser'` — the JWT payload `requireAuth` attached to the in-flight request
|
|
187
|
+
* (via `getCurrentUser()`), or `undefined` outside a request / without `requireAuth`
|
|
188
|
+
* - `` `$currentUser.<key>` `` — a single field plucked from that payload, e.g.
|
|
189
|
+
* `'$currentUser.id'` (pair with a `type` matching that field's shape)
|
|
190
|
+
*
|
|
191
|
+
* `'$increment'` is intentionally NOT a `default` code — see `FieldDefinition.sequence`
|
|
192
|
+
* instead. Auto-increment needs an async read-modify-write against a counters
|
|
193
|
+
* collection; mongoose resolves `default` synchronously, so it can't live here.
|
|
194
|
+
*
|
|
195
|
+
* Any other string/value passed to `default` is used as a literal default, unchanged.
|
|
196
|
+
*/
|
|
197
|
+
type DefaultOperator = '$now' | '$uuid' | '$objectId' | '$timestamp' | '$shortId' | '$currentUser' | `$currentUser.${string}`;
|
|
198
|
+
interface FieldDefinition {
|
|
199
|
+
type: PrimitiveFieldType | 'array';
|
|
200
|
+
required?: boolean;
|
|
201
|
+
unique?: boolean;
|
|
202
|
+
/** Creates a single-field index. Use `ModelOptions.indexes` for compound/TTL/text. */
|
|
203
|
+
index?: boolean;
|
|
204
|
+
/** A literal default value, or a `DefaultOperator` sentinel code (see above). */
|
|
205
|
+
default?: unknown;
|
|
206
|
+
/** Restricts the field to a fixed set of values. Valid on `string` and `number` types. */
|
|
207
|
+
enum?: readonly (string | number)[];
|
|
208
|
+
/** Inclusive bounds for `number` (and `date`) fields. */
|
|
209
|
+
min?: number | Date;
|
|
210
|
+
max?: number | Date;
|
|
211
|
+
/** Inclusive length bounds for `string` fields. */
|
|
212
|
+
minLength?: number;
|
|
213
|
+
maxLength?: number;
|
|
214
|
+
/** `string` fields must match this pattern. */
|
|
215
|
+
match?: RegExp;
|
|
216
|
+
/**
|
|
217
|
+
* Custom check: return `true` to accept, `false` or an error message to reject.
|
|
218
|
+
* May be async. Runs on create and on update of this field.
|
|
219
|
+
*/
|
|
220
|
+
validate?: (value: unknown) => boolean | string | Promise<boolean | string>;
|
|
221
|
+
/** Model name to reference. Valid on `objectId` types (bare or as an array's `of`). */
|
|
222
|
+
ref?: string;
|
|
223
|
+
/**
|
|
224
|
+
* Item type for `array` fields: a primitive (`of: 'string'`) or a nested schema for an
|
|
225
|
+
* array of embedded documents (`of: { sku: {...}, qty: {...} }`). Omit for an untyped array.
|
|
226
|
+
*/
|
|
227
|
+
of?: PrimitiveFieldType | ModelSchema;
|
|
228
|
+
/**
|
|
229
|
+
* Typed fields for an embedded `object`, e.g.
|
|
230
|
+
* `{ type: 'object', required: true, fields: { city: {...}, zip: {...} } }`.
|
|
231
|
+
* Without `fields`, an `object` stores any JSON value unvalidated.
|
|
232
|
+
*/
|
|
233
|
+
fields?: ModelSchema;
|
|
234
|
+
/**
|
|
235
|
+
* Auto-increments a shared counter and assigns it on insert, before `required`
|
|
236
|
+
* validation runs. `true` uses `'<ModelName>.<field>'` as the counter key; a string
|
|
237
|
+
* sets an explicit key so multiple fields/models can share one counter (e.g. a
|
|
238
|
+
* global order number). MongoDB stores counters in `efc_counters`; PostgreSQL uses a
|
|
239
|
+
* real `SEQUENCE`. Only supported on top-level fields.
|
|
240
|
+
*/
|
|
241
|
+
sequence?: boolean | string;
|
|
242
|
+
}
|
|
243
|
+
/**
|
|
244
|
+
* A schema field is one of:
|
|
245
|
+
* - a `FieldDefinition` (`{ type: 'string', required: true }`)
|
|
246
|
+
* - a nested `ModelSchema` — shorthand for an embedded object with typed fields:
|
|
247
|
+
* `address: { city: { type: 'string' }, zip: { type: 'string' } }`
|
|
248
|
+
* - a one-element tuple holding a nested `ModelSchema` — an array of embedded
|
|
249
|
+
* documents: `items: [{ sku: { type: 'string' } }]`
|
|
250
|
+
*/
|
|
251
|
+
type SchemaField = FieldDefinition | ModelSchema | [ModelSchema] | readonly [ModelSchema];
|
|
252
|
+
/** Field types `defineTable` accepts: the portable ones plus SQL-native types. */
|
|
253
|
+
type TablePrimitiveFieldType = PrimitiveFieldType
|
|
254
|
+
/** `integer` (int4) — a JS `number`, whole and 32-bit. */
|
|
255
|
+
| 'integer'
|
|
256
|
+
/** `bigint` (int8) — a JS `bigint`. */
|
|
257
|
+
| 'bigint'
|
|
258
|
+
/** `numeric(precision, scale)` — exact; values are decimal `string`s. */
|
|
259
|
+
| 'decimal'
|
|
260
|
+
/** `uuid` — a `string`. */
|
|
261
|
+
| 'uuid'
|
|
262
|
+
/** `jsonb` — any JSON value, unvalidated. */
|
|
263
|
+
| 'json';
|
|
264
|
+
interface TableFieldDefinition extends Omit<FieldDefinition, 'type' | 'of' | 'fields' | 'min' | 'max'> {
|
|
265
|
+
type: TablePrimitiveFieldType | 'array';
|
|
266
|
+
/** Inclusive bounds; `bigint`/`decimal` fields also take `bigint` / decimal strings. */
|
|
267
|
+
min?: number | bigint | string | Date;
|
|
268
|
+
max?: number | bigint | string | Date;
|
|
269
|
+
/** `decimal` only: total significant digits (`numeric(precision, scale)`). */
|
|
270
|
+
precision?: number;
|
|
271
|
+
/** `decimal` only: digits after the decimal point. */
|
|
272
|
+
scale?: number;
|
|
273
|
+
/** A string `enum` stored as a PostgreSQL `ENUM` type instead of a `CHECK` constraint. */
|
|
274
|
+
nativeEnum?: boolean;
|
|
275
|
+
/** The column name, when it differs from the field name (top-level fields only). */
|
|
276
|
+
column?: string;
|
|
277
|
+
/**
|
|
278
|
+
* Item type for `array` fields. A scalar type becomes a native PostgreSQL array
|
|
279
|
+
* (`text[]`, `integer[]`, …); a nested schema is stored as `jsonb`.
|
|
280
|
+
*/
|
|
281
|
+
of?: TablePrimitiveFieldType | TableSchema;
|
|
282
|
+
fields?: TableSchema;
|
|
283
|
+
}
|
|
284
|
+
type TableSchemaField = TableFieldDefinition | TableSchema | [TableSchema] | readonly [TableSchema];
|
|
285
|
+
interface TableSchema {
|
|
286
|
+
[field: string]: TableSchemaField;
|
|
287
|
+
}
|
|
288
|
+
interface ModelSchema {
|
|
289
|
+
[field: string]: SchemaField;
|
|
290
|
+
}
|
|
291
|
+
type SortDirection = 1 | -1 | 'asc' | 'desc';
|
|
292
|
+
interface ModelQueryOptions {
|
|
293
|
+
/** Resolve `objectId` fields that have a `ref` into the referenced records. */
|
|
294
|
+
populate?: string | string[];
|
|
295
|
+
/** Only return these fields (`id` is always included). */
|
|
296
|
+
select?: string[];
|
|
297
|
+
}
|
|
298
|
+
interface FindOptions extends ModelQueryOptions {
|
|
299
|
+
/** e.g. `{ createdAt: -1, name: 'asc' }` — keys are applied in order. */
|
|
300
|
+
sort?: Record<string, SortDirection>;
|
|
301
|
+
limit?: number;
|
|
302
|
+
skip?: number;
|
|
303
|
+
}
|
|
304
|
+
interface IndexDefinition {
|
|
305
|
+
/** Field → direction (`1` / `-1`), or `'text'` for a full-text index. */
|
|
306
|
+
fields: Record<string, 1 | -1 | 'text'>;
|
|
307
|
+
unique?: boolean;
|
|
308
|
+
/** MongoDB TTL index: documents expire this many seconds after the indexed date. */
|
|
309
|
+
expireAfterSeconds?: number;
|
|
310
|
+
name?: string;
|
|
311
|
+
}
|
|
312
|
+
interface ModelOptions {
|
|
313
|
+
/**
|
|
314
|
+
* `true` (the default) adds `createdAt`/`updatedAt`; `false` disables both;
|
|
315
|
+
* an object renames or selectively disables one, e.g.
|
|
316
|
+
* `{ createdAt: 'created_at', updatedAt: false }`.
|
|
317
|
+
*/
|
|
318
|
+
timestamps?: boolean | {
|
|
319
|
+
createdAt?: string | false;
|
|
320
|
+
updatedAt?: string | false;
|
|
321
|
+
};
|
|
322
|
+
/** Compound, TTL and text indexes. Applied by `Model.sync()`. */
|
|
323
|
+
indexes?: IndexDefinition[];
|
|
324
|
+
/** Collection (MongoDB) or table (PostgreSQL) name. Default: mongoose's pluralised lowercase name. */
|
|
325
|
+
collection?: string;
|
|
326
|
+
}
|
|
327
|
+
/** `defineTable` options: everything in `ModelOptions`, plus PostgreSQL-native keys and naming. */
|
|
328
|
+
interface TableOptions extends ModelOptions {
|
|
329
|
+
/**
|
|
330
|
+
* Primary key: `'uuid'` (default, `gen_random_uuid()`), `'serial'` (an `integer` identity —
|
|
331
|
+
* ids are `number`s) or `'bigserial'` (a `bigint` identity — ids are `bigint`s).
|
|
332
|
+
*/
|
|
333
|
+
id?: 'uuid' | 'serial' | 'bigserial';
|
|
334
|
+
/**
|
|
335
|
+
* `'snake_case'` maps field names to snake_case columns (`createdAt` → `created_at`) and
|
|
336
|
+
* the table name (`OrderItem` → `order_items`); records keep the field names. A field's
|
|
337
|
+
* `column` overrides it. Default: columns are named like the fields.
|
|
338
|
+
*/
|
|
339
|
+
naming?: 'snake_case';
|
|
340
|
+
}
|
|
341
|
+
/** Comparison operators accepted in filters (the MongoDB query subset both engines support). */
|
|
342
|
+
interface FilterOperators<V> {
|
|
343
|
+
$eq?: V | null;
|
|
344
|
+
$ne?: V | null;
|
|
345
|
+
$gt?: V;
|
|
346
|
+
$gte?: V;
|
|
347
|
+
$lt?: V;
|
|
348
|
+
$lte?: V;
|
|
349
|
+
$in?: V[];
|
|
350
|
+
$nin?: V[];
|
|
351
|
+
$exists?: boolean;
|
|
352
|
+
$regex?: string | RegExp;
|
|
353
|
+
}
|
|
354
|
+
type FilterValue<V> = V extends readonly (infer I)[] ? I | V | FilterOperators<I> : V | FilterOperators<V> | null;
|
|
355
|
+
/**
|
|
356
|
+
* Query filter. Plain values match by equality (an array field matches if it contains
|
|
357
|
+
* the value); operators cover comparisons; `$and` / `$or` combine; dotted paths
|
|
358
|
+
* (`'address.city'`) reach into embedded objects. `id` maps to the primary key.
|
|
359
|
+
*/
|
|
360
|
+
type Filter<T> = {
|
|
361
|
+
[K in keyof T]?: FilterValue<T[K]>;
|
|
362
|
+
} & {
|
|
363
|
+
id?: string | FilterOperators<string>;
|
|
364
|
+
$and?: Filter<T>[];
|
|
365
|
+
$or?: Filter<T>[];
|
|
366
|
+
[dottedPath: `${string}.${string}`]: unknown;
|
|
367
|
+
};
|
|
368
|
+
/** Update document: plain fields (shorthand for `$set`) and/or update operators. */
|
|
369
|
+
type Update<T> = Partial<T> | {
|
|
370
|
+
$set?: Partial<T> & {
|
|
371
|
+
[dottedPath: `${string}.${string}`]: unknown;
|
|
372
|
+
};
|
|
373
|
+
$unset?: {
|
|
374
|
+
[K in keyof T]?: true | 1 | '';
|
|
375
|
+
};
|
|
376
|
+
$inc?: {
|
|
377
|
+
[K in keyof T]?: number;
|
|
378
|
+
};
|
|
379
|
+
$push?: {
|
|
380
|
+
[K in keyof T]?: unknown;
|
|
381
|
+
};
|
|
382
|
+
$pull?: {
|
|
383
|
+
[K in keyof T]?: unknown;
|
|
384
|
+
};
|
|
385
|
+
};
|
|
386
|
+
type ModelRecord<T> = T & {
|
|
387
|
+
id: string;
|
|
388
|
+
};
|
|
389
|
+
/** Fields of `T` that hold a single scalar value — the fields `distinct()` accepts. */
|
|
390
|
+
type ScalarKeys<T> = {
|
|
391
|
+
[K in keyof T]-?: NonNullable<T[K]> extends string | number | bigint | boolean | Date ? K : never;
|
|
392
|
+
}[keyof T] & string & keyof T;
|
|
393
|
+
interface ModelCRUD<T extends object, TCreate = Partial<T>> {
|
|
394
|
+
readonly name: string;
|
|
395
|
+
find(filter?: Filter<T>, options?: FindOptions): Promise<ModelRecord<T>[]>;
|
|
396
|
+
findById(id: string, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>;
|
|
397
|
+
findOne(filter: Filter<T>, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>;
|
|
398
|
+
/** `true` if at least one record matches. */
|
|
399
|
+
exists(filter: Filter<T>): Promise<boolean>;
|
|
400
|
+
/**
|
|
401
|
+
* The distinct non-null values of a scalar field among matching records, sorted
|
|
402
|
+
* ascending. Array and object fields are rejected (the engines disagree on them).
|
|
403
|
+
*/
|
|
404
|
+
distinct<K extends ScalarKeys<ModelRecord<T>>>(field: K, filter?: Filter<T>): Promise<NonNullable<ModelRecord<T>[K]>[]>;
|
|
405
|
+
create(data: TCreate): Promise<ModelRecord<T>>;
|
|
406
|
+
createMany(data: TCreate[]): Promise<ModelRecord<T>[]>;
|
|
407
|
+
/** Validates changed fields (enum, min/max, custom validators) before writing. */
|
|
408
|
+
update(id: string, data: Update<T>): Promise<ModelRecord<T> | null>;
|
|
409
|
+
/**
|
|
410
|
+
* Updates the first record matching `filter` (in one statement) and returns it, or
|
|
411
|
+
* `null` if nothing matched. Which record is "first" is unspecified when several match.
|
|
412
|
+
*/
|
|
413
|
+
updateOne(filter: Filter<T>, data: Update<T>): Promise<ModelRecord<T> | null>;
|
|
414
|
+
/** Returns the number of records modified. */
|
|
415
|
+
updateMany(filter: Filter<T>, data: Update<T>): Promise<number>;
|
|
416
|
+
/**
|
|
417
|
+
* Applies `update` to the first record matching `filter`, or creates `create` if none
|
|
418
|
+
* matches; returns the resulting record. `create` is used as given — fields of `filter`
|
|
419
|
+
* are not copied into it. Only a unique index on the filtered fields makes concurrent
|
|
420
|
+
* upserts race-free: a duplicate (409) on create is retried once as an update.
|
|
421
|
+
*/
|
|
422
|
+
upsert(filter: Filter<T>, create: TCreate, update: Update<T>): Promise<ModelRecord<T>>;
|
|
423
|
+
delete(id: string): Promise<void>;
|
|
424
|
+
/** Deletes the first record matching `filter` and returns it, or `null` if none matched. */
|
|
425
|
+
deleteOne(filter: Filter<T>): Promise<ModelRecord<T> | null>;
|
|
426
|
+
/** Returns the number of records deleted. */
|
|
427
|
+
deleteMany(filter: Filter<T>): Promise<number>;
|
|
428
|
+
count(filter?: Filter<T>): Promise<number>;
|
|
429
|
+
/** MongoDB aggregation pipeline. Throws on PostgreSQL — use `db.query()` there. */
|
|
430
|
+
aggregate<R = Record<string, unknown>>(pipeline: Record<string, unknown>[]): Promise<R[]>;
|
|
431
|
+
/**
|
|
432
|
+
* The engine-native object: the mongoose `Model` on MongoDB, the Drizzle `pgTable`
|
|
433
|
+
* on PostgreSQL. Compiles the model if no query has run yet.
|
|
434
|
+
*/
|
|
435
|
+
raw(): Promise<unknown>;
|
|
436
|
+
/**
|
|
437
|
+
* Reconciles the database with the model: creates the collection/table, adds missing
|
|
438
|
+
* columns, converts changed column types, relaxes constraints the model dropped and
|
|
439
|
+
* creates/removes indexes. Never drops a column or data. Runs automatically on first
|
|
440
|
+
* use unless `autoSync: false`. Returns the changes made — or, with `dryRun`, the
|
|
441
|
+
* changes it would make (SQL on PostgreSQL, index operations on MongoDB).
|
|
442
|
+
*/
|
|
443
|
+
sync(options?: {
|
|
444
|
+
dryRun?: boolean;
|
|
445
|
+
}): Promise<string[]>;
|
|
446
|
+
/** Drops the collection/table and all its data. For migration `down()` functions. */
|
|
447
|
+
drop(): Promise<void>;
|
|
448
|
+
}
|
|
449
|
+
type Simplify<T> = {
|
|
450
|
+
[K in keyof T]: T[K];
|
|
451
|
+
} & {};
|
|
452
|
+
type PrimitiveValue<P> = P extends 'string' | 'objectId' | 'uuid' | 'decimal' ? string : P extends 'number' | 'integer' ? number : P extends 'bigint' ? bigint : P extends 'boolean' ? boolean : P extends 'date' ? Date : unknown;
|
|
453
|
+
/** What a field accepts on writes: dates parse from strings, numbers widen exact types. */
|
|
454
|
+
type InputPrimitive<P> = P extends 'date' ? Date | string | number : P extends 'bigint' ? bigint | number : P extends 'decimal' ? string | number : PrimitiveValue<P>;
|
|
455
|
+
/** `I` = input mode (create data) instead of record mode. */
|
|
456
|
+
type InferDefinition<F, I extends boolean> = F extends {
|
|
457
|
+
type: 'array';
|
|
458
|
+
} ? F extends {
|
|
459
|
+
of: infer O;
|
|
460
|
+
} ? O extends TablePrimitiveFieldType ? (I extends true ? InputPrimitive<O> : PrimitiveValue<O>)[] : InferObject<O, I>[] : unknown[] : F extends {
|
|
461
|
+
type: 'object';
|
|
462
|
+
} ? F extends {
|
|
463
|
+
fields: infer S;
|
|
464
|
+
} ? InferObject<S, I> : unknown : F extends {
|
|
465
|
+
enum: readonly (infer E)[];
|
|
466
|
+
} ? E : F extends {
|
|
467
|
+
type: infer P;
|
|
468
|
+
} ? I extends true ? InputPrimitive<P> : PrimitiveValue<P> : never;
|
|
469
|
+
type InferField<F, I extends boolean> = F extends readonly [infer S] ? InferObject<S, I>[] : F extends {
|
|
470
|
+
type: TablePrimitiveFieldType | 'array';
|
|
471
|
+
} ? InferDefinition<F, I> : InferObject<F, I>;
|
|
472
|
+
/** Fields always present on a stored record: required, defaulted or sequence-assigned. */
|
|
473
|
+
type PresentKeys<S> = {
|
|
474
|
+
[K in keyof S]: S[K] extends {
|
|
475
|
+
required: true;
|
|
476
|
+
} | {
|
|
477
|
+
default: unknown;
|
|
478
|
+
} | {
|
|
479
|
+
sequence: true | string;
|
|
480
|
+
} ? K : never;
|
|
481
|
+
}[keyof S];
|
|
482
|
+
/** Fields a create call must supply: required, with no default and no sequence. */
|
|
483
|
+
type MandatoryKeys<S> = {
|
|
484
|
+
[K in keyof S]: S[K] extends {
|
|
485
|
+
required: true;
|
|
486
|
+
} ? S[K] extends {
|
|
487
|
+
default: unknown;
|
|
488
|
+
} | {
|
|
489
|
+
sequence: true | string;
|
|
490
|
+
} ? never : K : never;
|
|
491
|
+
}[keyof S];
|
|
492
|
+
type InferObject<S, I extends boolean> = I extends true ? Simplify<{
|
|
493
|
+
-readonly [K in MandatoryKeys<S>]: InferField<S[K], true>;
|
|
494
|
+
} & {
|
|
495
|
+
-readonly [K in Exclude<keyof S, MandatoryKeys<S>>]?: InferField<S[K], true> | undefined;
|
|
496
|
+
}> : Simplify<{
|
|
497
|
+
-readonly [K in PresentKeys<S>]: InferField<S[K], false>;
|
|
498
|
+
} & {
|
|
499
|
+
-readonly [K in Exclude<keyof S, PresentKeys<S>>]?: InferField<S[K], false>;
|
|
500
|
+
}>;
|
|
501
|
+
type TimestampName<O, K extends 'createdAt' | 'updatedAt'> = O extends {
|
|
502
|
+
timestamps: false;
|
|
503
|
+
} ? never : O extends {
|
|
504
|
+
timestamps: infer TS extends object;
|
|
505
|
+
} ? TS extends {
|
|
506
|
+
[P in K]: infer N;
|
|
507
|
+
} ? N extends string ? N : never : K : K;
|
|
508
|
+
type TimestampFields<O> = {
|
|
509
|
+
[P in TimestampName<O, 'createdAt'> | TimestampName<O, 'updatedAt'>]: Date;
|
|
510
|
+
};
|
|
511
|
+
/** The record type a schema describes (without `id`), incl. the timestamps `O` enables. */
|
|
512
|
+
type InferSchema<S, O = object> = Simplify<InferObject<S, false> & TimestampFields<O>>;
|
|
513
|
+
/** The data `create()` accepts for a schema: required fields without a default are mandatory. */
|
|
514
|
+
type InferCreateInput<S> = InferObject<S, true>;
|
|
515
|
+
/** The model type `defineModel` returns: explicit generic, inferred, or loose for a widened schema. */
|
|
516
|
+
type InferredModel<T extends object, S, O> = [T] extends [never] ? string extends keyof S ? ModelCRUD<object> : ModelCRUD<InferSchema<S, O>, InferCreateInput<S>> : ModelCRUD<T>;
|
|
517
|
+
/**
|
|
518
|
+
* The record type of a model, `id` included:
|
|
519
|
+
* `type UserRecord = InferRecord<typeof User>`.
|
|
520
|
+
*/
|
|
521
|
+
type InferRecord<M> = M extends {
|
|
522
|
+
$types?: {
|
|
523
|
+
record: infer R;
|
|
524
|
+
};
|
|
525
|
+
} ? R : M extends ModelCRUD<infer T, unknown> ? Simplify<ModelRecord<T>> : never;
|
|
526
|
+
/** The data a model's `create()` accepts: `type NewUser = InferCreate<typeof User>`. */
|
|
527
|
+
type InferCreate<M> = M extends {
|
|
528
|
+
$types?: {
|
|
529
|
+
create: infer C;
|
|
530
|
+
};
|
|
531
|
+
} ? C : M extends {
|
|
532
|
+
create(data: infer C): unknown;
|
|
533
|
+
} ? C : never;
|
|
534
|
+
/** Passed to migration `up`/`down` functions and seed functions. */
|
|
535
|
+
interface MigrationContext {
|
|
536
|
+
/** The native client: a mongoose `Connection` (MongoDB) or a node-postgres `Pool`. */
|
|
537
|
+
db: unknown;
|
|
538
|
+
engine: DatabaseEngine;
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
export type { AuthStrategy as A, TableSchemaField as B, CacheConfig as C, DatabaseEngine as D, EFCConfig as E, FieldDefinition as F, Validator as G, InferSchema as I, LoggingConfig as L, ModelSchema as M, RouteEntry as R, Simplify as S, TaskOptions as T, Update as U, ValidationIssue as V, TaskDefinition as a, InferCreateInput as b, ModelOptions as c, InferredModel as d, TableSchema as e, TableOptions as f, CorsConfig as g, DefaultOperator as h, Filter as i, FilterOperators as j, FindOptions as k, IndexDefinition as l, InferCreate as m, InferRecord as n, MigrationContext as o, ModelCRUD as p, ModelQueryOptions as q, ModelRecord as r, RequestSchema as s, RouteMeta as t, RouteMethodMeta as u, RouteSchema as v, ScalarKeys as w, SchemaField as x, SortDirection as y, TableFieldDefinition as z };
|