@guren/core 1.13.0 → 1.14.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/index.d.ts CHANGED
@@ -2,43 +2,21 @@ import { ApiToken, ApiTokenStore, Command, Controller, Job, OAuthStatePayload, O
2
2
  import { AccessorDefinitions, AccessorFn, AwsDataApiDatabase, AwsDataApiDatabaseOptions, AwsDataApiSeederContext, BelongsToManyRecord, BelongsToManyRelationResult, BelongsToRecord, BelongsToRelationResult, BelongsToRequiredRecord, CastType, D1DatabaseHandle, D1DatabaseOptions, DrizzleAdapter, EagerLoadConstraint, FindManyOptions, GroupCondition, HasManyRecord, HasManyRelationResult, HasManyThroughRecord, HasManyThroughRelationResult, HasOneRecord, HasOneRelationResult, HookCallback, HookName, InferModelInsert, InferModelRecord, MassAssignmentException, MigrationRunSummary, MigrationStatusEntry, Model, Model as Model$1, ModelHooks, ModelNotFoundException, ModelObserver, ModelObserverConstructor, ModelPaginationMeta, ModelQueryOptions, MorphManyRecord, MorphManyRelationResult, MorphToRecord, MorphToRelationResult, MutatorDefinitions, MutatorFn, MySqlDatabase, MySqlDatabaseOptions, MySqlSeederContext, ORMAdapter, ORMAdapterAdvanced, OrderByClause, OrderByInput, OrderDefinition, OrderDirection, PaginateOptions, PaginatedResult, PlainObject, PlainObject as PlainObject$1, PostgresDatabase, PostgresDatabaseOptions, PostgresSeederContext, QueryBuilder, QueryBuilderOptions, ScopeFunction, SeederContext, SeederHandler, SeederRunSummary, SimpleCondition, SoftDeletes, SoftDeletesStatic, SqliteDatabase, SqliteDatabaseOptions, SqliteSeederContext, TransactionHandle, TransactionModelScope, WhereClause, WhereCondition, WhereGroupCallback, WhereOperator, WithRelations, createAwsDataApiDatabase, createD1Database, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, runSeeders } from "@guren/orm";
3
3
  export * from "@guren/server";
4
4
  //#region src/api-token-store.d.ts
5
- /**
6
- * Options for DatabaseApiTokenStore.
7
- */
8
5
  interface DatabaseApiTokenStoreOptions {
9
6
  /**
10
- * How the `abilities` column stores the ability list.
11
- *
12
- * - `'json'` (default) passes the array straight through — use with a
13
- * JSON-capable column (pg `jsonb`/`json`, sqlite `text(..., { mode: 'json' })`).
14
- * - `'text'` serializes to a JSON string for plain text columns.
15
- *
16
- * Reads always accept both representations.
7
+ * How the `abilities` column stores the ability list: `'json'` (default)
8
+ * passes the array through for a JSON-capable column (pg `jsonb`/`json`,
9
+ * sqlite `text(..., { mode: 'json' })`); `'text'` serializes to a JSON string.
10
+ * Reads accept both.
17
11
  * @default 'json'
18
12
  */
19
13
  abilitiesMode?: 'json' | 'text';
20
14
  }
21
15
  /**
22
- * Database-backed API token store built on the Guren ORM.
23
- *
24
- * Pass the Drizzle table for your `api_tokens` schema. Column property
25
- * names must match the {@link ApiToken} fields (`id`, `name`,
26
- * `hashedToken`, `userId`, `abilities`, `lastUsedAt`, `expiresAt`,
27
- * `createdAt`). The ORM must be configured (the standard
28
- * `DatabaseProvider` setup) before the store is used.
29
- *
30
- * @example
31
- * ```ts
32
- * import { DatabaseApiTokenStore, createApiToken } from '@guren/core'
33
- * import { apiTokens } from '@/db/schema'
34
- *
35
- * const store = new DatabaseApiTokenStore(apiTokens)
36
- *
37
- * const { plainTextToken } = await createApiToken(store, {
38
- * name: 'Mobile App Token',
39
- * userId: user.id,
40
- * })
41
- * ```
16
+ * Database-backed API token store built on the Guren ORM. Pass the Drizzle
17
+ * table for your `api_tokens` schema; column property names must match the
18
+ * {@link ApiToken} fields. Configure the ORM before use.
19
+ * @example `new DatabaseApiTokenStore(apiTokens)`
42
20
  */
43
21
  declare class DatabaseApiTokenStore implements ApiTokenStore {
44
22
  private readonly model;
@@ -51,60 +29,30 @@ declare class DatabaseApiTokenStore implements ApiTokenStore {
51
29
  deleteForUser(userId: string | number): Promise<void>;
52
30
  updateLastUsed(id: string, timestamp: Date): Promise<void>;
53
31
  /**
54
- * Delete tokens whose expiration time has passed. Expired tokens are
55
- * already rejected by `verifyApiToken`; call this from a scheduled
56
- * job to keep the table small.
32
+ * Delete tokens whose expiration has passed. `verifyApiToken` already rejects
33
+ * them; this only keeps the table small.
57
34
  */
58
35
  deleteExpired(now?: Date): Promise<void>;
59
36
  private deserialize;
60
37
  }
61
38
  //#endregion
62
39
  //#region src/session-store.d.ts
63
- /**
64
- * Options for DatabaseSessionStore.
65
- */
66
40
  interface DatabaseSessionStoreOptions {
67
41
  /**
68
- * How the `data` column stores the serialized session.
69
- *
70
- * - `'json'` (default) passes the object straight through — use with a
71
- * JSON-capable column (pg `jsonb`/`json`, sqlite `text(..., { mode: 'json' })`).
72
- * - `'text'` serializes to a JSON string for plain text columns.
73
- *
74
- * Reads always accept both representations.
42
+ * How the `data` column stores the serialized session: `'json'` (default)
43
+ * passes the object through for a JSON-capable column (pg `jsonb`/`json`,
44
+ * sqlite `text(..., { mode: 'json' })`); `'text'` serializes to a JSON string.
45
+ * Reads accept both.
75
46
  * @default 'json'
76
47
  */
77
48
  dataMode?: 'json' | 'text';
78
49
  }
79
50
  /**
80
- * Database-backed session store built on the Guren ORM — works on any
81
- * configured connection (SQLite, Postgres, MySQL, or Cloudflare D1), which
82
- * makes it the serverless default: no Redis required on Lambda, Vercel, or
83
- * Workers, and reads are strongly consistent (login → redirect → read works).
84
- *
85
- * Pass the Drizzle table for your `sessions` schema. Column property names
86
- * must match `id` (text primary key), `data`, and `expiresAt`:
87
- *
88
- * ```ts
89
- * export const sessions = sqliteTable('sessions', {
90
- * id: text('id').primaryKey(),
91
- * data: text('data', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
92
- * expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
93
- * })
94
- * ```
95
- *
96
- * Session values must be JSON-serializable: Dates come back as ISO strings,
97
- * `undefined` properties are dropped, and `bigint` values fail to serialize —
98
- * unlike `MemorySessionStore`, which keeps live references. Store primitives
99
- * and plain objects/arrays in sessions.
100
- *
101
- * @example
102
- * ```ts
103
- * import { DatabaseSessionStore } from '@guren/core'
104
- * import { sessions } from '@/db/schema'
105
- *
106
- * app.use(createSessionMiddleware({ store: new DatabaseSessionStore(sessions) }))
107
- * ```
51
+ * Database-backed session store built on the Guren ORM, the serverless default
52
+ * (no Redis on Lambda, Vercel, or Workers; reads are strongly consistent). Column
53
+ * property names of the `sessions` table must be `id` (text primary key), `data`,
54
+ * and `expiresAt`. Values must be JSON-serializable, unlike `MemorySessionStore`:
55
+ * Dates return as ISO strings, `undefined` properties drop, `bigint` throws.
108
56
  */
109
57
  declare class DatabaseSessionStore implements SessionStore {
110
58
  private readonly model;
@@ -114,17 +62,14 @@ declare class DatabaseSessionStore implements SessionStore {
114
62
  write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
115
63
  destroy(id: string): Promise<void>;
116
64
  /**
117
- * Refresh an existing session's TTL with a single conditional UPDATE — no
118
- * data rewrite, no existence check. Missing rows and rows that have
119
- * already expired (but not yet been swept) are left untouched, never
120
- * resurrected — matching the `SessionStore.touch` contract and the memory
121
- * store's behavior.
65
+ * Refresh an existing session's TTL with one conditional UPDATE. Missing and
66
+ * already-expired rows are left untouched, never resurrected, per the
67
+ * `SessionStore.touch` contract.
122
68
  */
123
69
  touch(id: string, ttlSeconds: number): Promise<void>;
124
70
  /**
125
- * Delete sessions whose expiration time has passed. Expired rows are
126
- * already treated as missing (and removed) by `read`; call this from a
127
- * scheduled job to keep the table small.
71
+ * Delete sessions whose expiration has passed. `read` already treats them as
72
+ * missing; this only keeps the table small.
128
73
  */
129
74
  deleteExpired(now?: Date): Promise<void>;
130
75
  private deserialize;
@@ -133,102 +78,44 @@ declare class DatabaseSessionStore implements SessionStore {
133
78
  //#endregion
134
79
  //#region src/oauth-state-store.d.ts
135
80
  /**
136
- * Database-backed OAuth state store built on the Guren ORM.
137
- *
138
- * The default `MemoryOAuthStateStore` keeps state in per-isolate memory,
139
- * which breaks on serverless: the OAuth authorize redirect and the callback
140
- * that follows it can land on different instances, so an in-memory map
141
- * never sees the state that was just written. Backing the store with the
142
- * database makes state visible to whichever instance handles the callback.
143
- *
144
- * Pass the Drizzle table for your `oauth_states` schema. Column property
145
- * names must match `stateHash` (text primary key), `provider`,
146
- * `redirectTo`, `expiresAt`, and `binding`:
147
- *
148
- * ```ts
149
- * export const oauthStates = sqliteTable('oauth_states', {
150
- * stateHash: text('state_hash').primaryKey(),
151
- * provider: text('provider').notNull(),
152
- * redirectTo: text('redirect_to'),
153
- * expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
154
- * binding: text('binding'),
155
- * })
156
- * ```
157
- *
158
- * `binding` is required for `authorize({ bindTo })` to survive the round trip
159
- * to the provider. Without the column the store cannot persist it, and every
160
- * bound state comes back unbound.
161
- *
162
- * @example
163
- * ```ts
164
- * import { createOAuthManager, DatabaseOAuthStateStore } from '@guren/core'
165
- * import { oauthStates } from '@/db/schema'
166
- *
167
- * export const oauth = createOAuthManager({
168
- * stateStore: new DatabaseOAuthStateStore(oauthStates),
169
- * })
170
- * ```
81
+ * Database-backed OAuth state store built on the Guren ORM, for serverless, where
82
+ * authorize and callback can land on different instances. Column property names
83
+ * of the `oauth_states` table must be `stateHash` (text primary key), `provider`,
84
+ * `redirectTo`, `expiresAt`, and `binding` (else `authorize({ bindTo })` states come back unbound).
85
+ * @example `new DatabaseOAuthStateStore(oauthStates)`
171
86
  */
172
87
  declare class DatabaseOAuthStateStore implements OAuthStateStore {
173
88
  private readonly model;
174
89
  constructor(table: unknown);
175
90
  store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
176
91
  find(stateHash: string): Promise<OAuthStatePayload | null>;
177
- /**
178
- * Fetch the row for `stateHash`, clearing it out and returning null if
179
- * expired. Shared by `find` and `consume`, which otherwise diverge only
180
- * in what they do with a live row.
181
- */
92
+ /** Fetch the row for `stateHash`, clearing it and returning null if expired. */
182
93
  private fetchLive;
183
94
  delete(stateHash: string): Promise<void>;
184
95
  /**
185
- * Atomically fetch and delete a state, guaranteeing exactly one concurrent
186
- * caller for the same hash receives the payload.
187
- *
188
- * This guarantee depends on the configured ORM adapter's `delete()`
189
- * reporting whether a row actually matched — either the deleted row
190
- * (RETURNING) or an affected-row count. `DrizzleAdapter`, the framework's
191
- * default and only shipped adapter, always does this: RETURNING drivers
192
- * (Postgres, SQLite, D1) resolve to the deleted row or `undefined` only
193
- * when zero rows matched; MySQL resolves to a result carrying
194
- * `affectedRows` (verified by inspection, not a dedicated test).
195
- *
196
- * The `ORMAdapter.delete` contract also permits a bare `void` return.
197
- * A custom adapter (via `Model.useAdapter()`) that returns `void`
198
- * unconditionally — on both a successful delete and a no-op — gives
199
- * `consume()` no way to tell which caller won: the value is identical for
200
- * both, so no post-hoc check can attribute the deletion. Rather than
201
- * silently rejecting every real login for such adapters,
202
- * `deleteRemovedRow` treats an unrecognized non-null result as removed —
203
- * this reopens the pre-consume find-then-delete race window (multiple
204
- * concurrent callers can pass) for adapters that can't report a match,
205
- * but does not break login. It is fail-closed (returns null / rejects)
206
- * only for `null`/`undefined`, DrizzleAdapter's definitive "no rows
207
- * matched" signal.
96
+ * Atomically fetch and delete a state, so exactly one concurrent caller for a
97
+ * hash receives the payload. Relies on `delete()` reporting a match
98
+ * (`DrizzleAdapter`: RETURNING row, or MySQL `affectedRows`). An adapter
99
+ * returning bare `void` reopens the find-then-delete race: `deleteRemovedRow`
100
+ * fails closed only on `null`/`undefined`, Drizzle's definitive "no rows matched".
208
101
  */
209
102
  consume(stateHash: string): Promise<OAuthStatePayload | null>;
210
103
  /**
211
- * Delete OAuth states whose expiration time has passed. Expired states
212
- * are already rejected by `find`; call this from a scheduled job to keep
213
- * the table small.
104
+ * Delete states whose expiration has passed. `find` already rejects them; this
105
+ * only keeps the table small.
214
106
  */
215
107
  deleteExpired(now?: Date): Promise<void>;
216
108
  }
217
109
  //#endregion
218
110
  //#region src/attachments/types.d.ts
219
111
  /**
220
- * Public types for the attachments layer (RFC 0013).
221
- *
222
- * One table, one service, one processor interface: attachments ride the ORM's
112
+ * Public types for the attachments layer (RFC 0013): attachments ride the ORM's
223
113
  * polymorphic `attachable` morph convention, bytes live on a `StorageManager`
224
114
  * disk, and image work happens behind {@link ImageProcessor}.
225
115
  */
226
116
  /**
227
- * A named image variant specification, declared on the model via
228
- * `hasOneAttached({ variants: { thumb: { width: 320 } } })`.
229
- *
230
- * `fit` is limited to what `Bun.Image` actually supports (`'fill'` and
231
- * `'inside'`); `'cover'` is reserved for a future, non-breaking addition.
117
+ * A named image variant specification. `fit` is limited to what `Bun.Image`
118
+ * supports; `'cover'` is reserved for a future, non-breaking addition.
232
119
  */
233
120
  interface VariantSpec {
234
121
  width?: number;
@@ -244,17 +131,11 @@ interface VariantSpec {
244
131
  quality?: number;
245
132
  }
246
133
  /**
247
- * Per-variant status entry stored in the attachment row's `variants` JSON
248
- * column. Every *declared* variant gets an entry at attach time — recording
249
- * declared names, not just generated ones, is what lets `attachmentUrl()`
250
- * distinguish "not yet generated" (fall back to the original) from "never
251
- * declared" (throw) after a reload.
252
- *
253
- * - `pending` — generation is queued (`attach(..., { queued: true })`)
254
- * and a worker has not finished it yet
255
- * - `ready` — the variant object exists at `path`
256
- * - `failed` — generation was attempted and failed
257
- * - `unavailable` — the runtime has no image processor
134
+ * Per-variant status entry in the row's `variants` JSON column. Every *declared*
135
+ * variant gets an entry at attach time, which lets `attachmentUrl()` tell "not
136
+ * yet generated" (fall back) from "never declared" (throw). `pending` is queued,
137
+ * `ready` means the object exists at `path`, `failed` was attempted,
138
+ * `unavailable` means the runtime has no processor.
258
139
  */
259
140
  interface AttachmentVariantRecord {
260
141
  status: 'pending' | 'ready' | 'failed' | 'unavailable';
@@ -266,9 +147,7 @@ interface AttachmentVariantRecord {
266
147
  /** Encoded size in bytes. */
267
148
  size?: number;
268
149
  }
269
- /**
270
- * A row of the `attachments` table, as returned by the attachment statics.
271
- */
150
+ /** A row of the `attachments` table, as returned by the attachment statics. */
272
151
  interface AttachmentRecord {
273
152
  /** ULID — sortable, unguessable object-key prefix. */
274
153
  id: string;
@@ -298,12 +177,9 @@ interface AttachmentRecord {
298
177
  updatedAt: Date;
299
178
  }
300
179
  /**
301
- * The resource-facing shape returned by `withAttachments()`, ready for
302
- * `JsonResource.toArray()` so pages can carry typed attachment props.
303
- *
304
- * `variants` has an entry for every *declared* variant name; a variant that
305
- * is not `ready` yet falls back to the original's URL, so pages keep
306
- * rendering (the `placeholder` LQIP covers the perceived-latency gap).
180
+ * The resource-facing shape returned by `withAttachments()`. `variants` has an
181
+ * entry for every *declared* variant name; one that is not `ready` yet falls
182
+ * back to the original's URL, so pages keep rendering.
307
183
  */
308
184
  interface AttachmentData {
309
185
  id: string;
@@ -322,22 +198,17 @@ interface AttachmentData {
322
198
  }>;
323
199
  }
324
200
  /**
325
- * Image processing behind the attachments pipeline.
326
- *
327
- * The default implementation wraps `Bun.Image` and is resolved only when the
328
- * runtime has it; apps on other runtimes may inject their own (e.g. a
329
- * sharp-backed one) via `configureAttachments({ processor })`.
330
- *
331
- * Implementations signal an OS-level codec gap by throwing an error whose
332
- * `code` is `'ERR_IMAGE_FORMAT_UNSUPPORTED'` — format support is a runtime
333
- * property (OS codecs), never a static table, so that error code is the only
334
- * authority the pipeline branches on.
201
+ * Image processing behind the attachments pipeline. The default wraps
202
+ * `Bun.Image`; other runtimes inject their own via
203
+ * `configureAttachments({ processor })`. An OS-level codec gap is signalled by
204
+ * throwing with `code === 'ERR_IMAGE_FORMAT_UNSUPPORTED'`; format support is a
205
+ * runtime property, so that code is the only thing the pipeline branches on.
335
206
  */
336
207
  interface ImageProcessor {
337
208
  /**
338
- * Full decode: validates the bytes, enforces `maxPixels`, reports
339
- * dimensions. Header sniffing is *not* validation — truncated files pass
340
- * it — so implementations must decode pixels before resolving.
209
+ * Full decode: validates the bytes, enforces `maxPixels`, reports dimensions.
210
+ * Header sniffing is *not* validation (truncated files pass it), so
211
+ * implementations must decode pixels before resolving.
341
212
  */
342
213
  probe(input: Uint8Array, limits: {
343
214
  maxPixels: number;
@@ -356,33 +227,24 @@ interface ImageProcessor {
356
227
  }>;
357
228
  }
358
229
  /**
359
- * What an attachment collection accepts as image input.
360
- *
361
- * - unset — opaque bytes: no image pipeline at all, `width`/`height`/
362
- * `placeholder` stay `null` (a `draftPdf` collection)
363
- * - `'allow'` — images are decoded and measured when recognized; anything
364
- * else is stored as opaque bytes
365
- * - `'require'`— input must be a decodable image; non-images are rejected
366
- * with a 422 `ValidationException`
367
- * - `'forbid'` — inputs that sniff as images are rejected with 422
230
+ * What an attachment collection accepts as image input. Unset means opaque
231
+ * bytes with no image pipeline; `'allow'` decodes recognized images and stores
232
+ * anything else opaquely; `'require'` and `'forbid'` reject with a 422.
368
233
  */
369
234
  type ImagePolicy = 'forbid' | 'allow' | 'require';
370
235
  /**
371
- * The bytes-only attach input. Filesystem path strings are deliberately not
372
- * accepted anywhere in this API: `Bun.Image`'s path form is an
373
- * arbitrary-file-read primitive if a user-influenced string ever reaches it,
374
- * so the pipeline never exposes the shape at all.
236
+ * The bytes-only attach input. Filesystem path strings are never accepted:
237
+ * `Bun.Image`'s path form is an arbitrary-file-read primitive once a
238
+ * user-influenced string reaches it.
375
239
  */
376
240
  type AttachmentSource = File | Blob | Uint8Array;
377
241
  //#endregion
378
242
  //#region src/attachments/declaration.d.ts
379
243
  /**
380
- * How HEIC/HEIF input is handled. The default is `'reject'` (415): HEIC
381
- * decoding depends on OS codecs — it works on macOS dev machines and fails
382
- * on Linux production — and the default must not let that skew pass
383
- * silently. `'convert'` opts in: the service attempts decode-and-convert to
384
- * JPEG and still answers 415 when the runtime cannot decode HEIC
385
- * (`ERR_IMAGE_FORMAT_UNSUPPORTED`).
244
+ * How HEIC/HEIF input is handled. Defaults to `'reject'` (415) because HEIC
245
+ * decoding depends on OS codecs — it works on macOS dev machines and fails on
246
+ * Linux production. `'convert'` opts into decode-and-convert to JPEG, still
247
+ * answering 415 when the runtime cannot decode HEIC.
386
248
  */
387
249
  type HeicPolicy = 'reject' | 'convert';
388
250
  interface AttachedCollectionOptions<V extends string = never> {
@@ -399,10 +261,9 @@ interface AttachedCollectionOptions<V extends string = never> {
399
261
  variants?: Record<V, VariantSpec>;
400
262
  }
401
263
  /**
402
- * One collection's declaration as stored on the model's
403
- * `static attachments`. Produced by {@link hasOneAttached} /
404
- * {@link hasManyAttached}; the generics carry the collection kind and the
405
- * declared variant names into the mixin's compile-time checks.
264
+ * One collection's declaration as stored on the model's `static attachments`.
265
+ * The generics carry the collection kind and the declared variant names into
266
+ * the mixin's compile-time checks.
406
267
  */
407
268
  interface AttachmentCollectionSpec<TKind extends 'one' | 'many' = 'one' | 'many', V extends string = string> {
408
269
  kind: TKind;
@@ -416,26 +277,11 @@ interface AttachmentCollectionSpec<TKind extends 'one' | 'many' = 'one' | 'many'
416
277
  type AttachmentsDeclaration = Record<string, AttachmentCollectionSpec<'one' | 'many', string>>;
417
278
  /**
418
279
  * Declare a single-attachment collection (`attach` replaces the previous
419
- * attachment, purging its row and objects).
420
- *
421
- * @example
422
- * export class Post extends Attachable(defineModel(posts), {
423
- * cover: hasOneAttached({
424
- * image: 'require',
425
- * variants: { thumb: { width: 320 }, og: { width: 1200 } },
426
- * }),
427
- * draftPdf: hasOneAttached(), // opaque bytes; width/height/placeholder null
428
- * }) {}
280
+ * attachment, purging its row and objects). Called with no options the bytes
281
+ * stay opaque: width/height/placeholder are null.
429
282
  */
430
283
  declare function hasOneAttached<const V extends string = never>(options?: AttachedCollectionOptions<V>): AttachmentCollectionSpec<'one', V>;
431
- /**
432
- * Declare a multi-attachment collection (`attach` appends).
433
- *
434
- * @example
435
- * export class Post extends Attachable(defineModel(posts), {
436
- * images: hasManyAttached({ image: 'require' }),
437
- * }) {}
438
- */
284
+ /** Declare a multi-attachment collection (`attach` appends). */
439
285
  declare function hasManyAttached<const V extends string = never>(options?: AttachedCollectionOptions<V>): AttachmentCollectionSpec<'many', V>;
440
286
  //#endregion
441
287
  //#region src/attachments/engine.d.ts
@@ -445,23 +291,19 @@ interface AttachOptions {
445
291
  /** Disk to store on, overriding the configured default. */
446
292
  disk?: string;
447
293
  /**
448
- * Defer the full decode and variant generation to the queue: the request
449
- * path runs only the synchronous gates (byte cap, header dimensions, HEIC
450
- * signature), stores the original, seeds declared variants as `pending`,
451
- * and dispatches `GenerateVariantsJob`. Until the worker runs, variant
452
- * URLs fall back to the original. Requires a queue — either
453
- * `configureAttachments({ queue })` or an already-booted QueueManager.
294
+ * Defer the full decode and variant generation to the queue: the request path
295
+ * runs only the synchronous gates, stores the original, seeds declared
296
+ * variants as `pending`, and dispatches `GenerateVariantsJob`. Variant URLs
297
+ * fall back to the original until the worker runs. Requires a queue.
454
298
  */
455
299
  queued?: boolean;
456
300
  }
457
301
  interface ConfigureAttachmentsOptions {
458
302
  /**
459
- * The app's Drizzle `attachments` table (the app owns the table; the
460
- * framework ships the schema snippet — see the attachments guide).
461
- * Column property names must match the documented contract: `id`,
462
- * `attachableType`, `attachableId`, `collection`, `disk`, `path`, `name`,
463
- * `contentType`, `size`, `width`, `height`, `variants` (JSON-capable),
464
- * `placeholder`, `createdAt`, `updatedAt`.
303
+ * The app's Drizzle `attachments` table. Column property names must match the
304
+ * documented contract: `id`, `attachableType`, `attachableId`, `collection`,
305
+ * `disk`, `path`, `name`, `contentType`, `size`, `width`, `height`,
306
+ * `variants` (JSON-capable), `placeholder`, `createdAt`, `updatedAt`.
465
307
  */
466
308
  table: unknown;
467
309
  /** The app's StorageManager, resolved lazily (e.g. `() => container.make('storage')`). */
@@ -469,27 +311,21 @@ interface ConfigureAttachmentsOptions {
469
311
  /** Default disk name for new attachments. */
470
312
  disk: string;
471
313
  /**
472
- * Per-disk visibility (and, with the object form, how a private disk's
473
- * bytes are served — RFC 0015 §3). `'public'` disks serve via
474
- * `disk.url()`; `'private'` ones serve through the signed delivery route
475
- * when `delivery` is configured, else via `disk.temporaryUrl()`. Per
476
- * disk, not per attachment, because at least one driver (R2) has no
477
- * per-object visibility. Undeclared disks default to `'public'`.
314
+ * Per-disk visibility, and with the object form how a private disk's bytes are
315
+ * served (RFC 0015 §3). Per disk, not per attachment, because at least one
316
+ * driver (R2) has no per-object visibility. Undeclared disks are `'public'`.
478
317
  */
479
318
  disks?: Record<string, DiskDeliveryConfig>;
480
319
  /**
481
320
  * Signed delivery route configuration (RFC 0015). Presence switches
482
- * private-disk URLs from `disk.temporaryUrl()` to signed route URLs; the
483
- * route itself is mounted by `registerAttachmentRoutes(router)` in the
484
- * app's route registrar. Without this option nothing changes — v1
485
- * behaviour and its documented limitations stand.
321
+ * private-disk URLs from `disk.temporaryUrl()` to signed route URLs; the route
322
+ * itself is mounted by `registerAttachmentRoutes(router)`.
486
323
  */
487
324
  delivery?: DeliveryOptions;
488
325
  /**
489
- * Decode cap in pixels (decompression-bomb defense). Header-declared and
490
- * decoded dimensions above this are rejected before a pixel buffer is
491
- * allocated. No "unlimited" setting exists; photography/archival apps
492
- * raise it deliberately and should isolate their image workers.
326
+ * Decode cap in pixels (decompression-bomb defense); header-declared and
327
+ * decoded dimensions above it are rejected before a pixel buffer exists.
328
+ * There is deliberately no "unlimited" setting.
493
329
  * @default 52_000_000
494
330
  */
495
331
  maxPixels?: number;
@@ -500,23 +336,17 @@ interface ConfigureAttachmentsOptions {
500
336
  */
501
337
  maxImageBytes?: number;
502
338
  /**
503
- * Image processor override. Defaults to the Bun-native processor when the
504
- * runtime has `Bun.Image`; pass `null` to force the processor-less path
505
- * (variants recorded as `unavailable`, validation stops at the header
506
- * gates) or your own implementation (e.g. sharp-backed) on other runtimes.
339
+ * Defaults to the Bun-native processor when the runtime has `Bun.Image`. Pass
340
+ * `null` to force the processor-less path (variants `unavailable`, validation
341
+ * stops at the header gates), or your own implementation.
507
342
  */
508
343
  processor?: ImageProcessor | null;
509
344
  /**
510
- * The app's QueueManager, resolved lazily (e.g.
511
- * `() => container.make('queue')`). Enables `attach(..., { queued: true })`:
512
- * the engine materializes the manager's default driver and dispatches
513
- * `GenerateVariantsJob` on it. Materializing the default driver installs
514
- * it as the process-wide dispatch target (`QueueManager` semantics), so
515
- * pass the same manager the rest of the app dispatches through — a
516
- * second manager here would redirect every later `Job.dispatch()` in the
517
- * process. Without this option, `queued: true` falls back to the
518
- * globally configured queue driver and throws a clear error when there
519
- * is none.
345
+ * The app's QueueManager, resolved lazily; enables `attach(..., { queued })`.
346
+ * Materializing its default driver installs that driver process-wide, so pass
347
+ * the same manager the rest of the app dispatches through — a second one would
348
+ * redirect every later `Job.dispatch()`. Without this option, `queued: true`
349
+ * falls back to the globally configured driver.
520
350
  */
521
351
  queue?: () => unknown;
522
352
  /**
@@ -527,10 +357,9 @@ interface ConfigureAttachmentsOptions {
527
357
  urlExpiresIn?: number;
528
358
  }
529
359
  /**
530
- * What `GenerateVariantsJob` needs to finish a deferred attach. The specs
531
- * are snapshotted at dispatch time (they come from the model declaration,
532
- * never the call site), so an in-flight job is unaffected by later
533
- * declaration edits and the worker needs no model registry to resolve them.
360
+ * What `GenerateVariantsJob` needs to finish a deferred attach. Specs are
361
+ * snapshotted at dispatch time, so an in-flight job survives later declaration
362
+ * edits and the worker needs no model registry.
534
363
  */
535
364
  interface GenerateVariantsPayload {
536
365
  attachmentId: string;
@@ -539,15 +368,11 @@ interface GenerateVariantsPayload {
539
368
  variants?: Record<string, VariantSpec>;
540
369
  }
541
370
  /**
542
- * How a private disk's bytes are served behind the signed route
543
- * (RFC 0015 §3):
544
- * - `'auto'` (default): redirect when the driver positively declares
545
- * `capabilities.presignedGet`, else proxy. Declared, never probed —
546
- * `LocalDriver.temporaryUrl()` succeeds with a plain public URL, so a
547
- * probe would misclassify exactly the disk that must not redirect.
548
- * - `'redirect'` / `'proxy'`: force one behaviour.
549
- * - `'direct'`: bypass the route entirely — v1's raw `temporaryUrl()`
550
- * URLs, for disks that measured the extra hop and want it gone.
371
+ * How a private disk's bytes are served behind the signed route (RFC 0015 §3).
372
+ * `'auto'` redirects only on a driver's *declared* `capabilities.presignedGet`,
373
+ * never a probe: `LocalDriver.temporaryUrl()` succeeds with a plain public URL,
374
+ * so probing would misclassify exactly the disk that must not redirect.
375
+ * `'direct'` bypasses the route entirely for v1's raw `temporaryUrl()` URLs.
551
376
  */
552
377
  type DeliveryServeMode = 'auto' | 'redirect' | 'proxy' | 'direct';
553
378
  type DiskDeliveryConfig = 'public' | 'private' | {
@@ -556,8 +381,7 @@ type DiskDeliveryConfig = 'public' | 'private' | {
556
381
  };
557
382
  /**
558
383
  * Per-URL options for `attachmentUrl()`. `disposition` accepts only
559
- * `'attachment'`: `inline` is already the default outcome for allowlisted
560
- * types, and the route's allowlist can never be forced to inline — a
384
+ * `'attachment'`: the route's allowlist can never be forced to inline, so a
561
385
  * signed `inline` value would change the URL while doing nothing.
562
386
  */
563
387
  interface AttachmentUrlOptions {
@@ -571,28 +395,18 @@ interface DeliveryOptions {
571
395
  */
572
396
  prefix?: string;
573
397
  /**
574
- * Named-route name `registerAttachmentRoutes` registers under.
575
- * `Router.name()` silently overwrites duplicates, so the default is
576
- * reserved for the framework.
398
+ * `Router.name()` silently overwrites duplicates, so the default is reserved
399
+ * for the framework.
577
400
  * @default 'attachments.show'
578
401
  */
579
402
  routeName?: string;
580
403
  }
581
404
  /**
582
405
  * The single storage key prefix every attachment object lives under:
583
- * `attachments/<id>/<name>` for an original, `attachments/<id>/variants/…`
584
- * for a derivative, and `attachments/` itself for the prune sweep's
585
- * directory listing.
586
- *
587
- * Exported, and re-exported from `@guren/core`, because the layout is not
588
- * private to this file. `guren check`'s attachments rules judge, from
589
- * another package, whether uploaded bytes land somewhere the app serves
590
- * statically — and the ones that reach the objects themselves have to name
591
- * `<disk root>/attachments` to do it. A restated copy of the prefix over
592
- * there does not fail loudly when this layout moves (a shard level, a
593
- * rename): it stops matching, answers "not reachable", and reports an
594
- * exposed app as safe. A build-failing security rule failing *open*, with
595
- * nothing going red anywhere. Import this instead of restating it.
406
+ * `attachments/<id>/<name>` originals, `attachments/<id>/variants/…`
407
+ * derivatives, `attachments/` the prune sweep's listing. Exported because
408
+ * `guren check` names `<disk root>/attachments` from another package; a restated
409
+ * copy there would stop matching when this moves and report an exposed app safe.
596
410
  */
597
411
  declare const ATTACHMENT_OBJECT_PREFIX = "attachments";
598
412
  declare const DEFAULT_DELIVERY_ROUTE_NAME = "attachments.show";
@@ -605,17 +419,16 @@ interface PruneOptions {
605
419
  interface PruneReport {
606
420
  /** Rows examined. */
607
421
  scannedRows: number;
608
- /** Rows whose owning record no longer exists (deleted unless dry-run). */
422
+ /** Rows whose owning record is gone (deleted unless dry-run). */
609
423
  orphanRows: Array<{
610
424
  id: string;
611
425
  attachableType: string;
612
426
  attachableId: string;
613
427
  }>;
614
428
  /**
615
- * Morph types that could not be verified and were left untouched: types
616
- * missing from `Model.morphMap`, or whose existence query failed. A type
617
- * that cannot be checked is never treated as absent — that would turn an
618
- * outage into a mass deletion.
429
+ * Morph types that could not be verified and were left untouched. A type that
430
+ * cannot be checked is never treated as absent: that turns an outage into a
431
+ * mass deletion.
619
432
  */
620
433
  skippedTypes: Array<{
621
434
  type: string;
@@ -637,11 +450,9 @@ interface PruneReport {
637
450
  /** A record id accepted by the attachment statics (int and uuid/text PKs). */
638
451
  type AttachableRecordId = string | number;
639
452
  /**
640
- * The loosest shape a declaration member must have. Deliberately minimal:
641
- * a tighter bound (the full `AttachmentCollectionSpec`) would become the
642
- * contextual type of the `hasOneAttached()` / `hasManyAttached()` calls and
643
- * make TypeScript infer their variant-name parameter as `string` instead of
644
- * the declared keys — silently disabling every variant-name check.
453
+ * Deliberately minimal: a tighter bound would become the contextual type of the
454
+ * `hasOneAttached()` / `hasManyAttached()` calls and widen their variant-name
455
+ * parameter to `string`, disabling every variant-name check.
645
456
  */
646
457
  type DeclarationShape = Record<string, {
647
458
  kind: 'one' | 'many';
@@ -659,27 +470,24 @@ type DetachRest<TSpec> = TSpec extends {
659
470
  kind: 'many';
660
471
  } ? [attachmentId?: string] : [];
661
472
  /**
662
- * Rejects declaration keys that shadow a real column of the base model's
663
- * table (the attachment would hide the column at `withAttachments` time).
664
- * A base whose record type is untyped (`keyof` collapses to `string`) is
665
- * exempt — there is nothing concrete to check against.
473
+ * Rejects declaration keys that shadow a real column of the base model's table
474
+ * (the attachment would hide it at `withAttachments` time). A base whose record
475
+ * type is untyped is exempt.
666
476
  */
667
477
  type CollisionFreeDeclaration<TBase extends typeof Model$1, TDecl> = string extends keyof TBase['recordType'] & string ? unknown : { [K in Extract<keyof TDecl, keyof TBase['recordType']>]: never; };
668
478
  /**
669
- * The statics the `Attachable` mixin adds. All of them delegate to the
670
- * engine wired by `configureAttachments()`; every collection argument is
671
- * `keyof` the declaration, so typos, wrong kinds, and undeclared variant
672
- * names are compile errors.
479
+ * The statics the `Attachable` mixin adds, all delegating to the engine wired by
480
+ * `configureAttachments()`. Every collection argument is `keyof` the
481
+ * declaration, so typos and undeclared variant names are compile errors.
673
482
  */
674
483
  interface AttachableStatic<TBase extends typeof Model$1, TDecl extends DeclarationShape> {
675
484
  /** The declaration, statically readable (this is what `guren check` and codegen read). */
676
485
  readonly attachments: TDecl;
677
486
  /**
678
- * Store bytes as an attachment on `collection`. `source` is bytes only
679
- * (`File | Blob | Uint8Array`) — path strings are never accepted. On a
680
- * `hasOne` collection the previous attachment is replaced (row and
681
- * objects purged); on `hasMany` the new one is appended. Validation and
682
- * variant specs come from the declaration, not the call site.
487
+ * Store bytes as an attachment on `collection`. `source` is bytes only — path
488
+ * strings are never accepted. `hasOne` replaces the previous attachment (row
489
+ * and objects purged); `hasMany` appends. Validation and variant specs come
490
+ * from the declaration, not the call site.
683
491
  */
684
492
  attach<K extends keyof TDecl & string>(recordId: AttachableRecordId, collection: K, source: AttachmentSource, options?: AttachOptions): Promise<AttachmentRecord>;
685
493
  /**
@@ -697,146 +505,76 @@ interface AttachableStatic<TBase extends typeof Model$1, TDecl extends Declarati
697
505
  id: string | number;
698
506
  }, K extends keyof TDecl & string>(records: readonly TRecord[], names: readonly K[]): Promise<Array<TRecord & AttachedProps<TDecl, K>>>;
699
507
  /**
700
- * URL for a collection's attachment: `disk.url()` on public disks; on
701
- * private ones a signed delivery-route URL when `delivery` is configured
702
- * (RFC 0015), else `disk.temporaryUrl()`. A declared-but-not-ready
703
- * variant falls back to the original; a variant name that was never
704
- * declared throws. `expiresIn` (ms) overrides the configured
705
- * `urlExpiresIn` for this one URL. Returns `null` when nothing is
706
- * attached.
508
+ * URL for a collection's attachment: `disk.url()` on public disks; on private
509
+ * ones a signed delivery-route URL when `delivery` is configured (RFC 0015),
510
+ * else `disk.temporaryUrl()`. A declared-but-not-ready variant falls back to
511
+ * the original; an undeclared variant name throws. `expiresIn` is in ms.
512
+ * Returns `null` when nothing is attached.
707
513
  */
708
514
  attachmentUrl<K extends keyof TDecl & string>(record: PlainObject$1 | AttachableRecordId, collection: K, options?: AttachmentUrlOptions & {
709
515
  variant?: VariantNamesOf<TDecl[NoInfer<K>]>;
710
516
  }): Promise<string | null>;
711
517
  /**
712
- * Remove every attachment of a record (all collections), objects first,
713
- * rows after. Call it from destroy actions — model delete hooks are not a
714
- * reliable purge trigger, so the contract is explicit-plus-sweep.
518
+ * Remove every attachment of a record, objects first, rows after. Call it from
519
+ * destroy actions: model delete hooks are not a reliable purge trigger.
715
520
  */
716
521
  purgeAttachments(recordId: AttachableRecordId): Promise<void>;
717
522
  }
718
523
  /**
719
- * Mixin that declares attachment collections on a model (RFC 0013). The
720
- * declaration is a static argument in the class heritage clause, so it is
721
- * statically readable (the same property `guren check` and `guren context`
722
- * rely on for the model's other surfaces), and its collection names, kinds,
723
- * and variant names are inferred as compile-time facts.
724
- *
725
- * Composes with other mixins the way `SoftDeletes` does.
726
- *
524
+ * Mixin declaring attachment collections on a model (RFC 0013). The declaration
525
+ * sits in the heritage clause so `guren check` and `guren context` read it
526
+ * statically while collection names, kinds, and variant names are inferred types.
727
527
  * @example
728
- * import { Attachable, hasOneAttached, hasManyAttached } from '@guren/core'
729
- *
730
- * export class Post extends Attachable(defineModel(posts), {
731
- * cover: hasOneAttached({
732
- * image: 'require',
733
- * variants: { thumb: { width: 320 }, og: { width: 1200 } },
734
- * }),
735
- * images: hasManyAttached({ image: 'require' }),
736
- * draftPdf: hasOneAttached(),
737
- * }) {}
738
- *
739
- * // Later, anywhere:
740
- * await Post.attach(post.id, 'cover', await this.file('cover'))
741
- * const [withCover] = await Post.withAttachments([post], ['cover'])
742
- * const url = await Post.attachmentUrl(post, 'cover', { variant: 'thumb' })
528
+ * class Post extends Attachable(defineModel(posts), { cover: hasOneAttached({ image: 'require' }), images: hasManyAttached() }) {}
743
529
  */
744
530
  declare function Attachable<TBase extends typeof Model$1, const TDecl extends DeclarationShape>(Base: TBase, declaration: TDecl & CollisionFreeDeclaration<TBase, TDecl>): TBase & AttachableStatic<TBase, TDecl>;
745
531
  //#endregion
746
532
  //#region src/attachments/configure.d.ts
747
533
  interface ConfiguredAttachments {
748
534
  /**
749
- * A ready-made model bound to the app's `attachments` table, with
750
- * `morphTo('attachable', 'attachable')` pre-declared — for morph relations
751
- * (`Post.morphMany('attachments', Attachment, 'attachable')`) and advanced
752
- * queries. The app-local name lives in app namespace; the framework itself
753
- * exports no bare `Attachment` (it would collide with the mail /
754
- * notification / Slack attachment vocabulary).
535
+ * A model bound to the app's `attachments` table with
536
+ * `morphTo('attachable', 'attachable')` pre-declared. The framework exports no
537
+ * bare `Attachment`: it would collide with the mail / notification / Slack
538
+ * attachment vocabulary.
755
539
  */
756
540
  Attachment: typeof Model$1;
757
541
  }
758
542
  /**
759
- * Wire the attachments layer, once per app (the `DatabaseSessionStore`
760
- * precedent: the app owns the table, the framework returns the model).
761
- * The attachment statics on `Attachable` models resolve this configuration
762
- * lazily and throw a clear error when it was never called.
763
- *
543
+ * Wire the attachments layer, once per app: the app owns the table, the
544
+ * framework returns the model. `Attachable` statics resolve this lazily and
545
+ * throw a clear error when it was never called.
764
546
  * @example
765
- * ```ts
766
- * // config/attachments.ts
767
- * import { configureAttachments } from '@guren/core'
768
- * import { attachments } from '@/db/schema'
769
- *
770
- * export const { Attachment } = configureAttachments({
771
- * table: attachments,
772
- * storage: () => container.make('storage'),
773
- * disk: 'media',
774
- * })
775
- * ```
547
+ * export const { Attachment } = configureAttachments({ table: attachments, storage: () => container.make('storage'), disk: 'media' })
776
548
  */
777
549
  declare function configureAttachments(options: ConfigureAttachmentsOptions): ConfiguredAttachments;
778
550
  //#endregion
779
551
  //#region src/attachments/delivery.d.ts
780
552
  /**
781
- * The signed attachment delivery route's controller (RFC 0015 §1). Thin on
782
- * purpose: it hands the raw `Request` to the engine, which owns
783
- * verification, variant resolution, and the redirect/proxy split — so the
784
- * serving contract is testable without HTTP.
785
- *
786
- * Raw on purpose, too: every semantic parameter must be re-read from the
787
- * same `URLSearchParams` parse the signature canonicalizes with. Hono's
788
- * query decoder disagrees with `URLSearchParams` on malformed
789
- * percent-encoding, and a parser mismatch there is a signed-URL rewrite
790
- * primitive.
553
+ * The signed attachment delivery route's controller (RFC 0015 §1). It hands the
554
+ * *raw* `Request` to the engine so every semantic parameter is re-read from the
555
+ * same `URLSearchParams` parse the signature canonicalizes with: Hono's query
556
+ * decoder disagrees with `URLSearchParams` on malformed percent-encoding, and
557
+ * that mismatch is a signed-URL rewrite primitive.
791
558
  */
792
559
  declare class AttachmentDeliveryController extends Controller {
793
560
  show(): Promise<Response>;
794
561
  }
795
562
  /**
796
- * Mount the signed delivery route (RFC 0015 §6) — call it from the app's
797
- * route registrar:
798
- *
799
- * ```ts
800
- * // routes/web.ts
801
- * import { registerAttachmentRoutes } from '@guren/core'
802
- *
803
- * export function registerWebRoutes(router: Router): void {
804
- * registerAttachmentRoutes(router)
805
- * // …app routes…
806
- * }
807
- * ```
563
+ * Mount the signed delivery route (RFC 0015 §6) from the app's route registrar.
808
564
  *
809
- * Registration never throws and does not require `configureAttachments()`
810
- * to have run: route tooling (`routes:types`, `guren check`, audit,
811
- * OpenAPI) invokes registrars against a bare `Router` with no providers
812
- * booted, so a config-dependent throw here would break every inspection
813
- * tool. The controller resolves the engine per request instead; at runtime
814
- * providers register before routes mount, so the configured prefix and
815
- * route name are picked up whenever they exist.
565
+ * Never throws and does not require `configureAttachments()` to have run: route
566
+ * tooling invokes registrars against a bare `Router` with no providers booted.
567
+ * The controller resolves the engine per request instead.
816
568
  */
817
569
  declare function registerAttachmentRoutes(router: Router): void;
818
570
  //#endregion
819
571
  //#region src/attachments/prune-command.d.ts
820
572
  /**
821
- * Console sweeper for the attachments layer (RFC 0013 §8). The polymorphic
822
- * `attachableType`/`attachableId` pair cannot carry a foreign key, so no
823
- * database cascade exists; deletion is explicit (`purgeAttachments()` in
824
- * destroy actions) plus this sweep for whatever slipped past it — records
825
- * deleted through paths that never purged, and, with `--objects`, storage
826
- * prefixes left behind by crashed or raced jobs.
827
- *
828
- * Register it in the app's console kernel:
829
- *
830
- * ```ts
831
- * // src/console.ts
832
- * import { AttachmentsPruneCommand } from '@guren/core'
833
- * kernel.register(AttachmentsPruneCommand)
834
- * ```
835
- *
836
- * Orphan rows are detected by resolving each `attachableType` through
837
- * `Model.morphMap` and querying for the records — set
838
- * `Model.morphMap = { Post, User, ... }` for every model that declares
839
- * attachments, or their rows are reported as unverifiable and left alone.
573
+ * Console sweeper for the attachments layer (RFC 0013 §8): the polymorphic
574
+ * `attachableType`/`attachableId` pair carries no foreign key, so deletion is
575
+ * explicit (`purgeAttachments()`) plus this sweep. Register it in the console
576
+ * kernel. Orphans are found by resolving `attachableType` through `Model.morphMap`;
577
+ * a model missing there has its rows reported as unverifiable and left alone.
840
578
  */
841
579
  declare class AttachmentsPruneCommand extends Command {
842
580
  static signature: string;
@@ -846,28 +584,17 @@ declare class AttachmentsPruneCommand extends Command {
846
584
  //#endregion
847
585
  //#region src/attachments/generate-variants-job.d.ts
848
586
  /**
849
- * Queue job behind `attach(..., { queued: true })` (RFC 0013 Part 2): runs
850
- * the deferred full decode, converts HEIC originals where the collection
851
- * opted in, and generates the declared variants, flipping their `pending`
852
- * status records to `ready`/`failed`.
587
+ * Queue job behind `attach(..., { queued: true })` (RFC 0013 Part 2): the
588
+ * deferred full decode, opted-in HEIC conversion, and the declared variants.
853
589
  *
854
- * `configureAttachments()` registers this job, so any worker process that
855
- * boots the app's config can process it. The worker is where the image
856
- * work happens — point it at a runtime with an image processor (Bun with
857
- * `Bun.Image`, or a custom `configureAttachments({ processor })`), or every
858
- * variant settles as `unavailable`.
590
+ * The worker is where the image work happens — point it at a runtime with an
591
+ * image processor, or every variant settles as `unavailable`.
859
592
  */
860
593
  declare class GenerateVariantsJob extends Job<GenerateVariantsPayload> {
861
- /**
862
- * Pinned wire name: queued messages must survive bundler identifier
863
- * mangling and any future rename of this class.
864
- */
594
+ /** Pinned: queued messages must survive identifier mangling and renames. */
865
595
  static jobName: string;
866
596
  handle(payload: GenerateVariantsPayload): Promise<void>;
867
- /**
868
- * After the last retry, stop `pending` variants from looking in-flight
869
- * forever — their URLs already fall back to the original either way.
870
- */
597
+ /** After the last retry, stop `pending` variants looking in-flight forever. */
871
598
  failed(payload: GenerateVariantsPayload, _error: Error): Promise<void>;
872
599
  }
873
600
  //#endregion