runlify 0.0.794 → 0.0.797

package/docs/04-fields.md

@@ -0,0 +1,357 @@
+# Fields
+
+> **Load this file when:** you need to add or configure fields on an entity — scalar
+> fields, link fields, file/image fields, view-link fields, or the id field. Also covers
+> filters, display visibility, required/optional semantics, and indexes.
+>
+> Related: [03-entity-types.md](./03-entity-types.md) ·
+> [02-system-meta-builder.md](./02-system-meta-builder.md)
+
+---
+
+## Field types overview
+
+| Builder class | Created by | Used for |
+|--------------|-----------|---------|
+| `ScalarFieldBuilder` | `entity.addField()` | Primitive values: string, int, float, bool, datetime, date |
+| `IdFieldBuilder` | auto (always `id`) | Primary key of an entity |
+| `LinkFieldBuilder` | `entity.addLinkField()`, `addFileField()`, `addImageField()` | FK reference to another entity |
+| `ViewLinkFieldBuilder` | `entity.addViewLinkField()` | Read-only join, not a real FK column |
+
+---
+
+## Scalar types (`FieldType`)
+
+| Type | TypeScript | Prisma | Notes |
+|------|-----------|--------|-------|
+| `'string'` | `string` | `String` | Default. Use `setStringType()` to specialise |
+| `'int'` | `number` | `Int` | |
+| `'bigint'` | `bigint` | `BigInt` | |
+| `'float'` | `number` | `Float` | |
+| `'bool'` | `boolean` | `Boolean` | `searchable` set to `false` automatically |
+| `'datetime'` | `Date` | `DateTime` | |
+| `'date'` | `Date` | `DateTime` | Date only (no time component in UI) |
+
+Default type for new fields created via `addField()` is `'int'`. Always call
+`setType()` explicitly.
+
+---
+
+## String sub-types (`StringType`)
+
+Set via `field.setStringType(StringType.X)`. Only valid when `type === 'string'`.
+
+| Value | Effect | Notes |
+|-------|--------|-------|
+| `StringType.Plain` | Single-line text input | Default |
+| `StringType.Number` | Number-formatted string | Displayed as number but stored as string |
+| `StringType.Multiline` | Multi-line textarea | |
+| `StringType.RichEdit` | WYSIWYG rich text editor | |
+| `StringType.Markdown` | Markdown editor | Auto-sets `showInList=false`, `showInFilter=false` |
+| `StringType.Json` | JSON editor | Auto-sets `showInList=false`, `showInFilter=false` |
+
+---
+
+## Number sub-types (`NumberType`)
+
+Set via `field.setNumberType(NumberType.X)`. Only valid for `int`, `bigint`, `float`.
+
+| Value | Effect |
+|-------|--------|
+| `NumberType.Base` | Plain number (default) |
+| `NumberType.Money` | Formatted as monetary value in UI |
+
+---
+
+## BaseFieldBuilder — all methods
+
+Available on every field type.
+
+### Type & subtype
+
+#### `setType(type: FieldType): this` {#setType}
+
+Sets the scalar type. Validates that existing filters are compatible with the new type.
+When set to `'bool'`, automatically sets `searchable = false`.
+
+#### `setStringType(stringType: StringType): this` {#setStringType}
+
+Only for `type === 'string'`. Throws otherwise.
+
+#### `setNumberType(numberType: NumberType): this` {#setNumberType}
+
+Only for `type === 'int' | 'bigint' | 'float'`. Throws otherwise.
+
+---
+
+### Required / optional semantics {#required}
+
+#### `setRequired(value?: boolean): this`
+
+Marks the field as required in the DB (`NOT NULL`) and in GraphQL input types.
+Also sets `requiredOnInput = true` if it has not been set explicitly before.
+
+#### `setNotRequired(): this`
+
+Marks the field as optional (`NULL` allowed). Equivalent to `setRequired(false)`.
+
+#### `setRequiredOnInput(value: boolean, defaultValueExpression?: string): this`
+
+Controls whether the field is required in GraphQL **input types** independently of
+whether it is required in the DB. Use when the field is required in the DB but has a
+server-side default, so the client doesn't need to send it.
+
+---
+
+### Updatability {#updatability}
+
+#### `setNotUpdatableByUser(defaultValueExpression?, defaultBackendValueExpression?): this` {#setNotUpdatableByUser}
+
+Marks the field as **not updatable via user-facing GraphQL mutations**.
+Internally calls `setRequiredOnInput(false, defaultValueExpression)`.
+
+| Parameter | Description |
+|-----------|-------------|
+| `defaultValueExpression` | Frontend expression used as default value in create forms |
+| `defaultBackendValueExpression` | Server-side expression evaluated on create/update |
+
+**Anti-pattern — using `setNotUpdatableByUser` to make a field immutable when it is
+also `setRequired()`:**
+
+```ts
+// WRONG: setNotUpdatableByUser sets requiredOnInput=false
+// This means the field is optional in update input even though it is required in DB.
+// For a create-only field that the server fills, this is CORRECT.
+// For a field that the user MUST provide on create, use setRequiredOnInput explicitly:
+field
+  .setRequired()                    // required in DB
+  .setNotUpdatableByUser()          // NOT in update mutations
+  .setRequiredOnInput(true)         // required in CREATE mutation
+```
+
+**Anti-pattern — using `setNotUpdatableByUser` on every field to hide entity from UI:**
+
+```ts
+// WRONG: intended to make entity read-only, but breaks required/type semantics
+entity.addField('name').setRequired().setNotUpdatableByUser()
+entity.addField('code').setRequired().setNotUpdatableByUser()
+
+// CORRECT: hide at entity level
+entity.setCreatableByUser(false).setUpdatableByUser(false).setRemovableByUser(false)
+```
+
+See [03-entity-types.md#access-control](./03-entity-types.md#access-control).
+
+#### `setUpdatableByUser(): this`
+
+Reverses `setNotUpdatableByUser`. Marks field as editable by user again.
+
+#### `setUpdatable(value?: boolean): this`
+
+Controls whether the field appears in backend update operations at all (not just user-
+facing). Lower-level than `setUpdatableByUser`.
+
+---
+
+### Visibility {#visibility}
+
+All default to `true` except where noted.
+
+| Method | Controls |
+|--------|---------|
+| `setShowInList(value?)` | Shown in entity list table |
+| `setShowInFilter(value?)` | Shown in list filter panel |
+| `setShowInCreate(value?)` | Shown in create form |
+| `setShowInEdit(value?)` | Shown in edit form |
+| `setShowInShow(value?)` | Shown in record detail view |
+| `setHidden(value?)` | Hidden everywhere (UI + generated TS types) |
+| `setSearchable(value?)` | Included in full-text search indexing |
+
+`Markdown` and `Json` string types auto-set `showInList=false` and `showInFilter=false`.
+
+---
+
+### Default values {#defaults}
+
+#### `setDefaultDbValue(value: string | boolean | undefined): this`
+
+Sets the Prisma `@default(...)` value in the schema. This is a DB-level default.
+
+#### `setDefaultValueExpression(value: string): this`
+
+Sets the expression used on the **frontend** (create forms) and as the backend default
+expression. Cannot be `'null'` or `'undefined'` — throws.
+
+Also automatically calls `setDefaultBackendValueExpression(value)`.
+
+#### `setDefaultBackendValueExpression(value: string): this`
+
+Sets only the backend expression (TypeScript code evaluated during create/update).
+Cannot be `'null'` or `'undefined'` — throws.
+
+---
+
+### Filters {#filters}
+
+Default filter for all fields: `['equal']`.
+
+#### `setFilters(filters: Filter[]): this`
+
+Replaces the filter list entirely. Validates compatibility with the field type.
+
+#### `addFilter(filter: Filter): this` / `addFilters(filters: Filter[]): this`
+
+Adds one or more filters.
+
+#### `delFilter(filter: Filter): this`
+
+Removes a filter.
+
+**Allowed filters per type:**
+
+| Type | Allowed filters |
+|------|----------------|
+| `string` | `equal`, `defined`, `not_defined`, `in`, `not_in` |
+| `int`, `bigint`, `float` | `equal`, `defined`, `not_defined`, `in`, `not_in`, `lte`, `gte`, `lt`, `gt` |
+| `date`, `datetime` | `equal`, `defined`, `not_defined`, `lte`, `gte`, `lt`, `gt` |
+| `bool` | `equal`, `defined`, `not_defined` |
+
+**Anti-pattern — `in` / `not_in` on a scalar field:**
+
+```ts
+// WRONG: throws at build() time — 'in'/'not_in' only allowed on LinkFields
+entity.addField('statusCode').setType('string').addFilter('in')
+
+// CORRECT: 'in'/'not_in' is only valid on link fields
+entity.addLinkField('statuses', 'statusId').addFilter('in')
+```
+
+---
+
+### Other
+
+#### `setTitle(title: string, language?: string): this`
+
+Sets human-readable title for a language. Defaults to the system's default language.
+
+#### `setTitles(titles: Record<string, string>): this`
+
+Sets titles for multiple languages at once: `{ en: 'Name', ru: 'Имя' }`.
+
+#### `setNeedFor(text: string): this`
+
+Documents what this field is used for. Included in generated docs.
+
+#### `setSharded(value?: boolean): this`
+
+Marks this field as a sharding key. The field becomes part of the composite unique
+constraint that groups records in a shard.
+
+#### `setArray(value?: boolean): this`
+
+Marks the field as an array type in GraphQL and TypeScript output types.
+
+#### `setMeaning(meaning: 'img'): this`
+
+Marks the field with a semantic meaning. Currently only `'img'` is supported — hints
+the UI to render this string field as an image URL.
+
+---
+
+## IdFieldBuilder {#id-field}
+
+Accessed via `entity.getKey()`. Auto-created as `id`.
+
+#### `setType(type: TKeyFieldType): this`
+
+| Value | Prisma | Auto-generation |
+|-------|--------|----------------|
+| `'int'` | `Int` | `@default(autoincrement())` — default |
+| `'bigint'` | `BigInt` | `@default(autoincrement())` |
+| `'string'` | `String` | `@default(cuid())` |
+
+---
+
+## LinkFieldBuilder {#link-field}
+
+Created via `entity.addLinkField(entityNameOrBuilder, name, title?)`.
+
+**Name MUST end in `Id`** — validated on construction. Throws immediately if violated.
+
+```ts
+entity.addLinkField('statuses', 'statusId')   // correct
+entity.addLinkField('statuses', 'status')     // throws: must end in 'Id'
+```
+
+#### `setType(type: TKeyFieldType): this`
+
+Sets the FK column type: `'int'` (default), `'bigint'`, or `'string'`.
+When passing a `CatalogBuilder` instance to `addLinkField`, the type is inferred
+automatically from the target entity's key type.
+
+#### `setPredefinedLinkedEntity(value: 'none' | 'file'): this`
+
+`'file'` — marks this field as linking to the built-in `files` catalog with special
+file-upload UI treatment. Set automatically by `addFileField()` and `addImageField()`.
+
+#### `setFileType(type: 'plain' | 'image'): this`
+
+Only valid when `predefinedLinkedEntity === 'file'`. Throws otherwise.
+Set automatically by `addImageField()` to `'image'`.
+
+**Anti-pattern — using `addLinkField` for file/image fields:**
+
+```ts
+// WRONG: works but misses file-upload UI and correct type semantics
+entity.addLinkField('files', 'avatarId')
+
+// CORRECT: use the dedicated helpers
+entity.addFileField('documentId')    // file upload UI
+entity.addImageField('avatarId')     // image upload UI with preview
+```
+
+---
+
+## ViewLinkFieldBuilder {#view-link-field}
+
+Created via `entity.addViewLinkField(entityNameOrBuilder, name, title?)`.
+
+A **read-only join** — does not create a real FK column in the database. Used to display
+data from a related entity without storing a FK. The name must still end in `Id`.
+
+Use for: displaying computed or external references that should not be part of the
+entity's own schema.
+
+---
+
+## Convenience helpers on entity
+
+```ts
+entity.addFileField(name, title?)    // LinkField to 'files', predefined='file', fileType='plain'
+entity.addImageField(name, title?)   // LinkField to 'files', predefined='file', fileType='image'
+```
+
+---
+
+## Field name rules
+
+Field names must match `/^[a-zA-Z0-9]+$/`. No underscores, hyphens, or special chars.
+Validated on construction — throws immediately.
+
+**Anti-pattern — underscores or special chars in field names:**
+
+```ts
+// WRONG: throws immediately
+entity.addField('first_name')
+entity.addField('first-name')
+entity.addField('firstName!')
+
+// CORRECT
+entity.addField('firstName')
+```
+
+---
+
+> **Examples:** this file intentionally omits code examples. Add real usage examples
+> from the consuming project here. A reference metadata file is typically at
+> `src/meta/metadata.ts` in the meta project.

package/docs/05-custom-methods.md

@@ -0,0 +1,249 @@
+# Custom Methods
+
+> **Load this file when:** you need to add custom GraphQL operations (Query or Mutation)
+> beyond the standard CRUD — either at the system level or on a specific entity.
+> Also covers input/output models, args, return types, workers, and cron schedules.
+>
+> Related: [02-system-meta-builder.md#addMethod](./02-system-meta-builder.md#addMethod) ·
+> [03-entity-types.md#entity-methods](./03-entity-types.md#entity-methods)
+
+---
+
+## Where to add methods
+
+Methods can live on:
+
+| Scope | How to create | Generated location |
+|-------|--------------|-------------------|
+| **System-level** | `system.addMethod(name, type)` | Top-level GraphQL schema + `AdditionalService` |
+| **Entity-level** | `entity.addMethod(name, type)` | Inside entity's `<Entity>Service` |
+
+Standard CRUD methods (`all`, `create`, `update`, `delete`) are auto-generated on every
+savable entity. Do not add them manually.
+
+---
+
+## `addMethod(name, methodType, title?): MethodBuilder` {#addMethod}
+
+| Parameter | Type | Values |
+|-----------|------|--------|
+| `name` | `string` | Method name, `camelCase`, unique within the owner |
+| `methodType` | `MethodType` | `MethodType.Query` — read operation; `MethodType.Mutation` — write operation |
+| `title` | `string` | Optional human-readable title |
+
+Returns a `MethodBuilder`.
+
+---
+
+## MethodBuilder API
+
+### `setExportedToApi(value?: boolean): this` {#setExportedToApi}
+
+Exposes this method in the generated GraphQL schema. Default `false` for custom methods
+(standard CRUD methods are exported automatically via their own mechanism).
+
+Call `.setExportedToApi()` on any custom method that should be callable from the
+frontend.
+
+**Anti-pattern — forgetting `setExportedToApi`:**
+
+```ts
+// WRONG: method is generated in the service but NOT in the GraphQL schema
+entity.addMethod('recalculate', MethodType.Mutation)
+
+// CORRECT
+entity.addMethod('recalculate', MethodType.Mutation).setExportedToApi()
+```
+
+---
+
+### `setMethodType(type: MethodType): this`
+
+Changes the method type after creation.
+
+---
+
+### `setAsync(value?: boolean): this`
+
+Marks the method as `async`. Affects the generated service method signature.
+
+---
+
+### `setWorker(workerName: string): this` / `resetWorker(): this`
+
+Associates this method with a named worker. The worker must be registered via
+`system.addWorker(name)`. When a worker is set, the method runs in the worker process
+rather than the main backend.
+
+---
+
+### `addRunSchedule(cronExpression: string): this` / `resetRunSchedule(): this`
+
+Adds a cron expression to automatically trigger this method on a schedule.
+Multiple schedules can be added. Duplicate cron expressions throw.
+
+```ts
+method.addRunSchedule('0 * * * *')   // every hour
+method.addRunSchedule('0 0 * * *')   // every day at midnight
+```
+
+---
+
+### `getArgsModel(): ArgsModelBuilder` {#argsModel}
+
+Returns the **args model** — the input type for this method. Add fields to it to define
+what the caller must pass.
+
+`ArgsModelBuilder` extends `BaseModelBuilder` — it has the same `addField()` and
+`addModelField()` API (see [Models section](#models) below).
+
+---
+
+### Return type
+
+A method's return type is one of three variants. Set exactly one.
+
+#### `setReturnObjectModel(name: string): ReturnObjectBuilder` {#setReturnObjectModel}
+
+Sets return type to a custom object type. Returns a `ReturnObjectBuilder` which extends
+`BaseModelBuilder` — add fields to define the returned shape.
+
+The returned model name is auto-namespaced: `${methodName}${PascalCase(name)}`.
+
+`ReturnObjectBuilder` additionally supports:
+```ts
+returnModel.setArray(true)   // returns an array of objects
+```
+
+#### `setReturnScalarModel(): ReturnScalarBuilder` {#setReturnScalarModel}
+
+Sets return type to a scalar. Returns a `ReturnScalarBuilder` which extends
+`ScalarFieldBuilder` — call `setType()` to set the scalar type, `setArray()` to return
+an array of scalars.
+
+```ts
+const ret = method.setReturnScalarModel()
+ret.setType('string')
+ret.setArray()   // returns string[]
+```
+
+#### `setReturnVoidModel(name?: string): ReturnVoidBuilder` {#setReturnVoidModel}
+
+Sets return type to `void` (no return value). This is the **default** — methods start
+as void.
+
+---
+
+## Models — input and output {#models}
+
+Models are named TypeScript / GraphQL types used as method arguments or return values.
+They are defined on the owner (system or entity) and referenced by methods.
+
+### Creating models
+
+| Method | Type | Use as |
+|--------|------|--------|
+| `createGeneralModel(name, title?)` | `BaseModelBuilder` | Input or output |
+| `createInputModel(name, title?)` | `BaseModelBuilder` | Input only (GraphQL `input` type) |
+| `createOutputModel(name, title?)` | `BaseModelBuilder` | Output only (GraphQL `type`) |
+
+### `BaseModelBuilder` API
+
+#### `addField(name, title?): ScalarFieldBuilder`
+
+Adds a scalar field to the model. Returns a `ScalarFieldBuilder` with the full field API
+from [04-fields.md](./04-fields.md).
+
+#### `addModelField(model, name, title?): ModelFieldBuilder`
+
+Adds a reference to another model defined on the same owner. The referenced model must
+exist at the time of this call — throws if not found.
+
+```ts
+const address = system.createGeneralModel('address')
+address.addField('street').setType('string').setRequired()
+address.addField('city').setType('string').setRequired()
+
+const output = method.setReturnObjectModel('result')
+output.addModelField('address', 'shippingAddress')
+```
+
+#### `delField(name): this`
+
+Removes a field from the model.
+
+---
+
+## Full wiring example pattern
+
+```
+system
+  .addMethod('calculateDiscount', MethodType.Query)
+  .setExportedToApi()
+  .setAsync()
+  ┌─ .getArgsModel()
+  │     .addField('orderId').setType('int').setRequired()
+  │     .addField('promoCode').setType('string')
+  │
+  └─ .setReturnObjectModel('result')
+        .addField('discountPercent').setType('float').setRequired()
+        .addField('finalPrice').setType('float').setRequired()
+```
+
+The method name, args model, and return model combine to generate:
+- A GraphQL schema entry (`Query.calculateDiscount(orderId: Int!, promoCode: String): CalculateDiscountResult`)
+- A service method stub in the `Additional*Service.ts` file (yours to implement)
+
+---
+
+## Anti-patterns
+
+### Defining return shape via separate `createOutputModel` without linking it to the method
+
+**Wrong:**
+```ts
+system.createOutputModel('discountResult')  // created but never linked
+
+const method = system.addMethod('getDiscount', MethodType.Query)
+// forgot to call setReturnObjectModel()
+```
+
+**Why:** the model is generated but the method returns `void`. The GraphQL schema
+doesn't reference the model.
+
+**Correct:** always call one of `setReturnObjectModel`, `setReturnScalarModel`, or
+`setReturnVoidModel` explicitly. For object returns, the model is created and registered
+by `setReturnObjectModel` automatically — no need to pre-create it separately.
+
+---
+
+### Adding standard CRUD method names manually
+
+**Wrong:**
+```ts
+entity.addMethod('all', MethodType.Query)    // throws: 'all' already exists
+entity.addMethod('create', MethodType.Mutation)
+```
+
+**Why:** `all`, `create`, `update`, `delete` are auto-added by `BaseSavableEntityBuilder`
+constructor. Adding them again throws a duplicate name error.
+
+**Correct:** use only unique custom names.
+
+---
+
+### Duplicate cron expressions on the same method
+
+**Wrong:**
+```ts
+method.addRunSchedule('0 * * * *')
+method.addRunSchedule('0 * * * *')   // throws: duplicate cron
+```
+
+**Correct:** each cron expression must be unique per method.
+
+---
+
+> **Examples:** this file intentionally omits code examples. Add real usage examples
+> from the consuming project here. A reference metadata file is typically at
+> `src/meta/metadata.ts` in the meta project.