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.