Crud Automator

Crud Automator

Source Priority

Use local source as the contract:

1. src/interface/**, src/type/**, and exported barrels define public API shape.
2. test/unit/** and test/e2e/** show supported behavior.
3. docs/** and README.md explain behavior, but may drift and must be checked against source.

Default Workflow

1. Inspect the existing entity, service, controller, subscriber, policy, and DTO configuration.
2. Prefer native Crud Automator primitives before adding custom controllers, mappers, facades, or wrappers.
3. Verify route config against current interfaces before copying examples.
4. Validate Swagger, DTO shape, relation loading, subscriber firing, authorization decisions, and transaction behavior after meaningful changes.

Current Contract Reminders

• @ApiController() applies Nest @Controller() internally; use path.
• routes: {} is valid and still generates default CRUD routes; omitted route entries do not disable routes.
• Generated controller routes are CREATE, GET, GET_LIST, UPDATE (PUT /:id), PARTIAL_UPDATE (PATCH /:id), and DELETE.
• GET_MANY is service/function/subscriber-only, not a generated HTTP route.
• Route controls live under generation: generation.isEnabled, generation.shouldWriteToController, and generation.decorators.
• Route security lives under security.authentication and security.authorization.
• authentication.type is the principal category (USER, ADMIN, ACCOUNT, MERCHANT, or project string), not the bearer/security scheme.
• Route-level Swagger security schemes use authentication.securityRequirements; one object is an AND group and multiple objects are OR alternatives.
• Request config is target keyed with EApiControllerRequestTarget.BODY, PARAMETERS, and QUERY.
• Response config is target keyed with EApiControllerResponseTarget.RESPONSE.
• OpenAPI response headers live directly under response.headers, not under EApiControllerResponseTarget.RESPONSE.
• autoDto is validators-only. Entity ApiPropertyDescribe({ properties }) remains the capability baseline; generated GET_LIST request[QUERY].filter, order, and pagination own its generated query contract.
• ApiPropertyDescribe({ isAutoDtoEnabled: false }) keeps entity metadata, TypeORM behavior, and manual DTO use but removes the property from every generated BODY, PARAMETERS, QUERY, and RESPONSE DTO, generated Swagger relation components, and metadata-driven or typed client filter/order input. Omitted or true preserves normal generation.
• Route/DTO isEnabled: true, generated GET identity, read.scope.parameters, and query plans cannot re-enable a globally hidden property. Explicit ApiPropertyCopy may deliberately copy it to a manual DTO, but all other route/DTO, guard, and validation rules still apply. PAGE server-only defaults/tie-breakers may use the described scalar; CURSOR ordering cannot because it requires generated response exposure.
• Manual dto and autoDto route branches are mutually exclusive.
• A manual GET_LIST QUERY DTO is mutually exclusive with generated filter/order/pagination configuration. Manual RESPONSE DTOs remain compatible; CURSOR additionally requires Automator metadata proving its exact flat wrapper and same-name raw protected item fields.
• Generated GET accepts top-level identity: { parameter: "gameId" } to rename only its primary-key wire parameter. The service predicate and HOOKS/IAM canonical identity still use the actual primary field, while the response shape is unchanged. Identity-only GET is valid only when the controller path has no inherited dynamic parameters; otherwise the same route needs a complete read.scope.parameters mapping.
• Generated GET/GET_LIST read.scope.parameters is a non-empty array of { parameter, field } mappings. It must exactly cover every required scalar inherited controller-path parameter once, maps only to distinct described direct scalar fields, and is mutually exclusive with a manual PARAMETERS DTO. Wildcard and optional/grouped dynamic path parameters fail at bootstrap.
• Generated read scope creates a route-scoped PARAMETERS DTO and Swagger contract. GET includes its primary identity under the configured alias or the ordinary primary-field name; GET_LIST adds only inherited scope parameters. Identity/query predicates are AND-merged with path scope and then HOOKS/IAM scope without overwrite semantics.
• GET_LIST order config may declare server-only ordered defaultOrder and tieBreakers entries. These validate against all described direct scalar fields, including UUID columns that are not client-sortable. A client order pair replaces defaults, tie-breakers are appended, and duplicate fields keep the earlier entry.
• GET_LIST pagination defaults to PAGE. Explicit PAGE keeps required limit/page and the count envelope. CURSOR keeps required limit, accepts at most one of after/before, omits page, and returns only { items, nextCursor, previousCursor }.
• CURSOR is a generated-route mode over the existing service: the first window uses one getMany query with take = limit + 1; a cursor window adds exactly one opposite-direction take = 1 probe. It does not add a provider, read model, service, cursor table, or signing-key configuration.
• A CURSOR order must be explicit. Every possible order field must be a selected, persisted, described, non-null direct scalar with no TypeORM value transformer or accessor and must be unconditionally raw-exposed in the generated response; the entity must have one primary column, and that column must occur only as the final explicit tie-breaker and remain absent from the client order allowlist.
• CURSOR v1 is PostgreSQL-only and requires the standard text result parsers. Its exact TypeORM order-declaration matrix is: boolean; signed smallint and integer, including increment-generated columns physically emitted through SMALLSERIAL/SERIAL DDL; numeric enums backed by smallint or integer; signed bigint, including increment-generated BIGSERIAL DDL, exposed as canonical decimal BIGINT_STRING; and native uuid. Do not use smallserial, serial, or bigserial as TypeORM column type literals. Binary mode, custom extra.types, every other PostgreSQL storage type, and every other driver fail before CURSOR query I/O; PAGE is unchanged. ApiPropertyDescribe establishes the primitive wire category and raw exposure, but request-only bounds, lengths, patterns, and multipleOf do not constrain the opaque seek boundary. BIGINT_STRING never converts through Number. Entity @AfterLoad listeners are rejected at bootstrap; applicable active TypeORM afterLoad subscribers fail before query I/O. Active subscriber listenTo() targets and PostgreSQL parser configuration are trusted TypeORM extension code and must be deterministic.
• ApiPropertyDescribe object metadata uses dataType; manual ApiPropertyObject uses type.
• ApiPropertyDescribe relation metadata does not currently accept array options.
• GetDefaultStringFormatProperties(format) provides canonical defaults for supported string formats.
• BigInt string sign options use EApiGetDefaultStringFormatPropertiesBigIntStringSign; the old type alias and paired-suffix validator configuration internals were removed. Import supported symbols from the package root.
• Generated CREATE, UPDATE, and PARTIAL_UPDATE bodies omit date fields identified as CREATED_AT, RECEIVED_AT, or UPDATED_AT; responses retain them. Exclusion follows the semantic identifier rather than property names, and DATE remains writable.
• There is no custom-only/default-disabled controller mode. Disable all six generated routes explicitly when a controller should expose only custom routes.

Function And Transaction Model

• Service/function create and update receive DeepPartial<E> directly, not { body }.
• Service/function get, getList, and getMany receive TypeORM options.
• Generated service/context delete is Promise<void>; direct decorator internals have a known return-shape inconsistency, so document and test the intended surface before changing it.
• @ApiFunctionCustom({ action, entity, transaction }) is for custom service commands that need function lifecycle, subscribers, and transaction context.
• @ApiFunctionStep({ entity, transaction }) is for internal service helper methods that need transaction context but are not standalone actions; direct calls are valid when the selected transaction mode permits.
• Function steps do not create subscriber hooks, route metadata, Swagger metadata, or authorization action identities; do not model them as custom actions.
• @ApiService({ entity, functions }) can configure transaction modes for generated CRUD functions keyed by EApiFunctionType.CREATE, UPDATE, DELETE, GET, GET_LIST, and GET_MANY; omitted entries default to SUPPORTS, and CUSTOM belongs to @ApiFunctionCustom.
• Generated routes preflight the exact bound GET, GET_LIST, GET_MANY, UPDATE, and DELETE function before the Automator-managed route transaction or repository I/O. It must be produced for the same entity/type by @ApiService or the matching built-in @ApiFunction*; undecorated overrides, accessors, and instance shadows fail closed at that boundary. Direct service calls are outside this route check. Generated CREATE preflights its protected post-create GET, and UPDATE preflights a protected response-reload GET when required. This is the intentional 4.0 breaking boundary.
• Function execution transaction modes use EApiFunctionTransactionMode with transaction.mode; subscriber requirements use EApiFunctionSubscriberTransactionExpectation with transaction.expectation.
• Inside decorated service execution, use this.getApiFunctionContext() for operations, repository, eventManager, and getRepository.
• Inside @ApiFunctionStep, use this.getApiFunctionStepContext() for repository, eventManager, and getRepository; it intentionally omits operations.
• ApiFunctionTransactionScope.runWithDataSource(dataSource, { name }, callback) owns a named external transaction and passes its EntityManager to the callback; runWithEntityManager() is join-only and fails without an active Automator owner registry.
• Named scopes accept optional observation: { selectors, onSettled }. Select by exact entity constructor, native function/STEP type and method; configuration is copied before I/O, with at most 32 selectors and 256 reserved selected invocations per owner. Immutable output contains only selector index, native execution status and fractional callback duration, plus existing transaction outcome and dropped count. Durations include nested/context/subscriber work and are not isolated SQL or lock-wait time. Settlement runs once after the best-effort release attempt, context exit and terminal lifecycle, preserves native results/errors and does not await or propagate observer failures. Require bounded synchronous capture; STEP remains trace-only. Disabled/unmatched execution reads no clock, and preflight/startup failure creates no artificial measurement.
• onAfterCommit and onAfterRollback run once after the outer transaction ends. Their readonly context exposes the FUNCTION, ROUTE, or SCOPE owner/id, all ordered events, and subscriber-matched events; events contain operation metadata only, never arguments, bodies, entities, or results, and STEP is trace-only.
• Commit/rollback error lifecycle uses onBeforeErrorCommit, onAfterErrorCommit, onBeforeErrorRollback, and onAfterErrorRollback. Post-commit failures must remain distinguishable from database rollback.
• Use the public FormatErrorEvidenceForLog(error) utility when an application deliberately logs a caught error. It emits only a bounded ASCII error type and an optional validated five-character SQLSTATE discovered through own data descriptors. Never log the error object, message, stack, cause, driver error, query, parameters, request URL, headers, IP, profile, or subscriber context. FormatUnknownForLog remains unchanged and is not an error-sanitization boundary.
• ApiFunctionUpdate performs one ordinary decorated GET before onBeforeUpdate. Read the patch from context.result, the active manager repository when a transaction exists (otherwise the service base repository) from context.DATA.repository, and the top-level detached and frozen shallow snapshot from context.DATA.currentEntity.
• UPDATE does not deep-clone or deep-freeze currentEntity. Default SAVE keeps nested aliases, full entity/relation/cascade persistence and no explicit reread after before-subscribers. A missing decorated GET skips update-before hooks and flows through GET then UPDATE error lifecycle.
• UPDATE-only persistenceMode: EApiFunctionUpdatePersistenceMode.PATCH is supported by ApiFunctionUpdate, generic ApiFunction, and ApiService.functions[UPDATE]. It requires explicit REQUIRED/MANDATORY, the same complete equality primary key in every original/effective criteria branch, and flat selected writable direct columns. It writes only supplied fields (including explicit old values), preserves effective scope/soft-delete visibility at UPDATE and fresh-reads by criteria key/projection before AFTER without another Automator GET callback. Empty PATCH performs no UPDATE/version bump and rereads with effective scope. No initial row lock precedes UPDATE-before subscribers. Default SAVE is unchanged.
• PATCH obtains selected columns from actual effective GET options, never hydrated own keys or constructor defaults. Unselected (including default-hidden), primary, generated, managed timestamp/version/delete-date, relation and embedded fields are not writable; functions/accessors/proxies in patch data reject. Requested relation graphs/IDs, lazy/embedded hydration, initial locks and empty/ambiguous selects reject; ordinary unloaded relations and native load hooks remain supported, with eager loading explicitly disabled when needed. Use SAVE for entity/relation/cascade semantics. Neither mode auto-loads arbitrary custom-function entities.