@appweaver/create-weaver-app 1.4.1 → 1.5.0

package/skill/references/resources.md

@@ -51,6 +51,8 @@ function createModel(config: ResourceModelConfig, override ?: Partial<ResourceMo
 | `update`         | OperationConfig                | no       | -                     | Pick/omit fields for the update DTO.                                |
 | `export`         | Record\<string, ExportField>   | no       | -                     | CSV export field configuration.                                     |
 | `index`          | string[] \| string[][]         | no       | -                     | Database index definitions (`-field` desc, `+field` asc).           |
+| `unique`         | string[] \| string[][]         | no       | -                     | Composite unique constraints, in the same shape as `index`.         |
+| `softDelete`     | boolean                        | no       | `false`               | Mark deleted records instead of removing them.                      |
 
 ### ID field
 
@@ -145,6 +147,76 @@ const config = {
 | `updatedAt`   | boolean | `true`  | Add `updatedAt` timestamp field.                |
 | `createdById` | boolean | `true`  | Add `createdById` foreign key to the auth user. |
 
+### Soft delete
+
+A model with `softDelete` enabled keeps its deleted records in the database instead of removing them. The delete marks
+the record with two extra columns. They are hidden fields: typed on the full generated model type (i.e. `Post`), so
+server code can read them, but never part of any API request or response, nor of the OpenAPI document:
+
+| Column        | Type                | Description                                                            |
+|---------------|---------------------|------------------------------------------------------------------------|
+| `deletedAt`   | `DateTime?`         | When the record was deleted, `null` for a live record.                 |
+| `deletedById` | auth model id (`?`) | The user who deleted the record. Only added when an auth model exists. |
+
+`deletedById` is indexed like any other foreign key, but `deletedAt` is not. Every read filters on `deletedAt IS NULL`,
+so add the column to the indexes matching the queries of the model where it helps, i.e.
+`index: [['deletedAt', '-createdAt', 'id']]` for the default listing.
+
+```ts
+const config = {
+  softDelete: true
+};
+```
+
+The stored files of a soft deleted record are **kept** by default, so a manual restore loses nothing, while a record
+removed from the database loses them by default. Each file field decides for itself with `onResourceSoftDeleted` and
+`onResourceDeleted` (see [File fields](#file-fields)). A kept file is never served again, see
+[Files of deleted resources](./storage.md#deleting-all-files-on-resource-deletion).
+
+```ts
+const config = {
+  softDelete: true,
+  files: {
+    avatar: {}, // kept on soft delete, removed on a database delete
+    idScan: { onResourceSoftDeleted: 'delete' } // removed on both
+  }
+};
+```
+
+Soft deleted records are hidden from every read, so for API users a soft delete is indistinguishable from a real one:
+
+- `find`, `update` and `delete` respond with 404, `query`, `aggregate` and `export` leave the record out.
+- List relations and relation counts skip it, a single relation pointing at it reads as `null`.
+- Relation filters never match through it: `_some`, `_none`, `_every` and `_exists` only consider live records, and a
+  `null` filter on a single relation matches a deleted related record.
+- Connecting or inline updating it through a relation input is rejected with 400.
+- Its files are served as missing, whether they were kept or removed.
+
+Restoring a record, or reading the deleted ones, is not part of the API: set `deletedAt` and `deletedById` back to
+`null` in the database, on the record, on the records soft deleted with it and on the `File` rows of its kept files,
+which all share the same `deletedAt` value. Unique values of a deleted record stay taken until the row is removed.
+
+The delete follows the `onDelete` action of every relation referencing the record, mirroring a database delete:
+
+| `onDelete` of the referencing relation        | On soft delete                                                                      |
+|-----------------------------------------------|-------------------------------------------------------------------------------------|
+| `cascade`                                     | The referencing records are soft deleted with the same `deletedAt`, level by level. |
+| `restrict`, `noAction` (default if required)  | The delete fails with 409 while a live record references it.                        |
+| `setNull`, `setDefault` (default if optional) | The reference is kept, so a manual restore brings the link back.                    |
+
+A soft delete never runs the database cascade, so every model a soft deleted model cascades into must enable
+`softDelete` too. The application refuses to start and `weaver generate` fails otherwise:
+
+```
+Model 'Comment' must enable 'softDelete', since its relation 'Comment.post' cascades on delete from the soft deleted model 'Post'.
+```
+
+The framework owned `ApiKey` and `ConnectedAccount` models cascade from the auth model, so they enable `softDelete`
+automatically when the auth model does.
+
+After enabling `softDelete` on a model, regenerate the schema and create a migration (`weaver generate`, then
+`weaver migration new <name>`).
+
 ### Scalar field types
 
 All scalar fields share these common properties:
@@ -362,9 +434,10 @@ const config = {
 | `mappedBy`      | string                                          | -            | Name of the inverse relation on the target model.                        |
 | `required`      | boolean                                         | `true`       | Whether the relation is required (nullable foreign key if not required). |
 | `minItems`      | number                                          | -            | Minimum items for list relations.                                        |
-| `orphanRemoval` | boolean                                         | `false`      | Delete orphaned records when parent is deleted.                          |
+| `orphanRemoval` | boolean                                         | `false`      | Delete the related records an update removes from the relation.          |
 | `onDelete`      | ReferentialAction                               | -            | Foreign key action on delete.                                            |
 | `onUpdate`      | ReferentialAction                               | -            | Foreign key action on update.                                            |
+| `index`         | boolean                                         | `true`       | Index the foreign key column; `false` leaves it unindexed.               |
 | `input`         | RelationInput                                   | -            | Input DTO configuration.                                                 |
 | `output`        | RelationOutput                                  | -            | Output DTO configuration.                                                |
 
@@ -375,6 +448,15 @@ record fails with a foreign key violation while any child row still exists. Set
 rows are owned by the parent and meaningless without it. Optional owning relations (`required: false`) fall back to
 `setNull`, which already lets the referenced record be deleted.
 
+The stored files of the records a `cascade` removes are cleaned up together with the files of the deleted record. A
+model with soft delete applies the same actions itself, see its section.
+
+With `orphanRemoval: true`, an update deletes the related records it removes from the relation instead of only
+disconnecting them. The orphans are deleted like any other record: their stored files are removed following
+`onResourceDeleted` and the records cascading from them are removed too. Orphans of a model with `softDelete` enabled
+are soft deleted instead, keep their
+references for a manual restore, and keep their files unless a field sets `onResourceSoftDeleted: 'delete'`.
+
 #### Relationship types
 
 The `type` property declares the relation cardinality explicitly, and `owner` marks the side that holds the foreign key
@@ -610,16 +692,17 @@ const config = {
 };
 ```
 
-| Property            | Type                   | Description                                                                                                 |
-|---------------------|------------------------|-------------------------------------------------------------------------------------------------------------|
-| `mimeType`          | string \| RegExp       | Allowed MIME types (glob patterns like `'image/*'` supported).                                              |
-| `namePattern`       | string \| function     | File naming pattern or function (available variables are listed below).                                     |
-| `array`             | boolean                | Allow multiple files.                                                                                       |
-| `maxSize`           | number \| string       | Maximum file size (e.g. `'2 MB'`, `5242880`).                                                               |
-| `maxCount`          | number                 | Maximum number of files (for array fields).                                                                 |
-| `output`            | RelationOutput         | When to include file info in output, and its count. Takes no `include` or `maxDepth`.                       |
-| `onResourceDeleted` | `'delete'` \| `'keep'` | When the owning resource is deleted. `'delete'` (default) removes files from storage, `'keep'` leaves them. |
-| `image`             | ImageConfig            | Image compression and resize settings. Only applies to image MIME types (excluding GIF).                    |
+| Property                | Type                   | Description                                                                                                                                                                                 |
+|-------------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `mimeType`              | string \| RegExp       | Allowed MIME types (glob patterns like `'image/*'` supported).                                                                                                                              |
+| `namePattern`           | string \| function     | File naming pattern or function (available variables are listed below).                                                                                                                     |
+| `array`                 | boolean                | Allow multiple files.                                                                                                                                                                       |
+| `maxSize`               | number \| string       | Maximum file size (e.g. `'2 MB'`, `5242880`).                                                                                                                                               |
+| `maxCount`              | number                 | Maximum number of files (for array fields).                                                                                                                                                 |
+| `output`                | RelationOutput         | When to include file info in output, and its count. Takes no `include` or `maxDepth`.                                                                                                       |
+| `onResourceDeleted`     | `'delete'` \| `'keep'` | When the owning resource is removed from the database, also by a cascade or an orphan removal. `'delete'` (default) removes files from storage, `'keep'` retains them without serving them. |
+| `onResourceSoftDeleted` | `'delete'` \| `'keep'` | When the owning resource is soft deleted (see `softDelete`). `'keep'` (default) retains files for a manual restore without serving them, `'delete'` removes them from storage.              |
+| `image`                 | ImageConfig            | Image compression and resize settings. Only applies to image MIME types (excluding GIF).                                                                                                    |
 
 #### Available namePattern variables
 
@@ -820,6 +903,32 @@ index: [['status', '-createdAt']]           // @@index([status, createdAt(sort:
 
 The prefix is part of the index identity, so `['createdAt', '-createdAt']` emits two separate indexes.
 
+Every foreign key column (relation `<name>Id` columns, `createdById` and `deletedById`) is indexed automatically, since
+PostgreSQL and SQLite do not index them on their own. A foreign key is skipped when it is already unique (`oneToOne`
+relations and file fields) or when an explicit `index` or `unique` entry leads with it, so
+`index: [['categoryId', '-publishedAt']]` replaces the automatic `@@index([categoryId])`. Set `index: false` on a
+relation to leave its foreign key unindexed, i.e. for a rarely queried relation of a write-heavy model:
+
+```ts
+relations: {
+  author: { model: 'User', type: 'oneToMany', owner: true, index: false }
+}
+```
+
+The audit columns `createdById` and `deletedById` are always indexed.
+
+### Unique config
+
+`unique` takes the same shape as `index` and emits `@@unique` constraints. Use it for a combination of columns that must
+be unique together; a single column is better marked with the scalar's own `unique: true`:
+
+```ts
+unique: [['provider', 'providerAccountId']] // @@unique([provider, providerAccountId])
+```
+
+A create or update breaking the constraint fails in the database, so handle the conflict where concurrent writes can
+race to insert the same combination.
+
 ### Generated models
 
 `createModel` produces the following TypeBox schema models used internally by routes and services:

package/skill/references/security.md

@@ -280,8 +280,9 @@ exchange succeeds.
 ### Connected accounts
 
 `ConnectedAccount` pairs a provider account with a local user: `provider`, `providerAccountId`, `scope`, `lastLoginAt`
-(`createdAt` holds the link date) and a relation to the auth model, indexed on `[provider, providerAccountId]`. A
-provider account belongs to one user only — relinking it elsewhere fails with a 403.
+(`createdAt` holds the link date) and a relation to the auth model, unique on `[provider, providerAccountId]`. A
+provider account belongs to one user only — relinking it elsewhere fails with a 403, also when two first sign-ins race
+to create the link.
 
 The table exists when any OAuth2 provider is enabled; `SECURITY_OAUTH2_CONNECTED_ACCOUNTS_KEEP_DATABASE_TABLE=true`
 keeps it after disabling OAuth2, like `SECURITY_API_KEY_KEEP_DATABASE_TABLE` does for API keys.

package/skill/references/storage.md

@@ -328,11 +328,30 @@ await fileService.deleteFile(
 
 ### Deleting all files on resource deletion
 
-When a resource is deleted, files belonging to file fields configured with `onResourceDeleted: 'delete'` can be
-automatically cleaned up. This is handled by `deleteResourceFiles()`, which is called automatically by the framework's
-delete route handler.
+When a resource is deleted, its stored files are cleaned up automatically, as configured per file field:
 
-To enable automatic file cleanup, set `onResourceDeleted: 'delete'` on the file field in your model config:
+| Option                  | Applies to                                   | Default    |
+|-------------------------|----------------------------------------------|------------|
+| `onResourceDeleted`     | A resource removed from the database         | `'delete'` |
+| `onResourceSoftDeleted` | A soft deleted resource (model `softDelete`) | `'keep'`   |
+
+Both options behave the same way:
+
+- `'delete'` removes the file from the storage and its `File` row from the database.
+- `'keep'` retains the file in the storage and its `File` row in the database, e.g. for audit, but never serves it
+  again: the row is soft deleted with the same `deletedAt` and `deletedById` values as its resource, and downloads
+  respond with 404 whatever the file access type is.
+
+The resource service `delete` method removes them once the delete commits, whether it is called by the delete route or
+directly from code, together with the files of every record deleted with it through an `onDelete: 'cascade'` relation.
+The same happens to the orphans an `update` deletes through a relation with `orphanRemoval: true`.
+
+The kept files are marked in the same transaction as the delete, while the removed ones leave the storage once it
+commits. A model with `softDelete` enabled keeps the files of its deleted records by default, so a manual restore loses
+nothing; set `onResourceSoftDeleted: 'delete'` on a field to remove its files on a soft delete too.
+
+The framework never removes kept files by itself. Purging them after a retention period is up to the application, e.g.
+with a scheduled job removing the `File` rows with an old `deletedAt` and their stored files.
 
 ```ts
 const config = {
@@ -343,16 +362,20 @@ const config = {
     },
     documents: {
       array: true,
-      onResourceDeleted: 'keep' // opt out: files are kept
+      onResourceDeleted: 'keep' // opt out: files are retained, but no longer served
+    },
+    idScan: {
+      onResourceSoftDeleted: 'delete' // also removed when the resource is soft deleted
     }
   }
 };
 ```
 
-You can also call `deleteResourceFiles` manually if needed:
+You can also call `deleteResourceFiles` manually if needed, or `deleteResourcesFiles` for many records of one model:
 
 ```ts
 await fileService.deleteResourceFiles('Post', postId);
+await fileService.deleteResourcesFiles('Post', [firstId, secondId]);
 ```
 
 ### Owning resource reference