How an application is arranged once it is written in TypeScript — where handlers live, what registers them, and how business logic is kept apart from persistence. Distinct from typing, which is about the model being visible to the compiler; this is about the shape of the code around it.
How a CAP service is arranged once it is written in TypeScript — where handlers live, what registers them, and how business logic is kept apart from persistence. Distinct from typing, which is about the model being visible to the compiler; this is about the shape of the code around it.
The shape capire gives a TypeScript service is the JavaScript one: custom logic is a subclass of cds.ApplicationService, its handlers are registered in init() with on, before and after, and the runtime finds the implementation in a file named after the service definition or in a lib/ or handlers/ subfolder beside it. The toolchain around that is official too — cds watch detects TypeScript from a tsconfig.json and runs cds-tsx, and a cds build task shipped with @cap-js/cds-typer@cap-js/cds-typerGenerates TypeScript types from a CDS model.sap official, cap precompiles to JavaScript for production.
Not covered: At the service's own implementation class. None of the pages read here divides a service's handlers across several classes, gives a draft's own events a place apart from the active entity's, or names a layer between a handler and the database — so a project that wants a class per entity, or business logic kept apart from persistence, writes that arrangement itself.
No page read for this assessment states SAP's intent about the arrangement inside srv, so the relationship between the two sides is unassessed.
Different ways of deciding what makes a method a handler, which is the choice a reader faces here: a decorator on the class or the method, as in cds-ts-dispatcher@dxfrontier/cds-ts-dispatcherDecorator-driven handler registration for CAP in TypeScript, where handlers are declared on a class rather than wired up one by one in an init function.independent, cap, a method name matched by convention, as in cap-handler-frameworkcap-handler-frameworkConvention-based handler layer for CAP: methods named beforeCreate, onRead or afterUpdate are mapped automatically, with the draft lifecycle given its own explicit hooks rather than folded into the active-entity ones.independent, cap, or a folder layout that fixes where an entity's class goes, as in cds-plugin-handlerscds-plugin-handlersA CAP plugin that structures handlers as one file per entity, in a folder per service, instead of one service implementation that keeps growing.independent, cap. Beside them sits the persistence half, such as cds-ts-repository@dxfrontier/cds-ts-repositoryA typed BaseRepository over CAP entities, so persistence is called through a class with methods rather than through CQN written inline in each handler.independent, cap: the queries called through a class with methods instead of written as CQN inside the handler.
A draft-enabled entity's own events — NEW, PATCH, EDIT, SAVE and DISCARD — are handled in places of their own in a CAP service written in TypeScript, apart from the CREATE, UPDATE and DELETE handlers of the active entity.
Covers where a draft's events are handled and what gets a method there. The draft lifecycle itself, the drafts entity, the locking and the activation, is the runtime's and is draft-handling, not this outcome.
Remaining work: A handler class states that it handles drafts before the draft hooks are mapped, and what each hook does is the application's code. Which hook registers on the drafts entity and which on the active one follows the runtime's own rule.
Conditions: The entity is annotated @odata.draft.enabled: true
Remaining work: The method bodies are the application's. The draft decorators are offered for an entity whose model says drafts are enabled; the README frames them that way rather than as a general set.
Remaining work: Not established from the README. A project would have to find out whether a draft event reaches an annotated method at all.
The data access of a CAP service written in TypeScript is called through classes with methods rather than written as queries inside the event handlers, so a handler holds the business logic and the queries sit behind one object.
Covers where the queries live and what calls them. Which database is underneath, the transaction they run in, and whether the entity types are generated are not this outcome.
Remaining work: The repository class itself is the application's, or the matching package. The decorators place the object; what it does for a given entity is written either way.
Remaining work: Which methods a given entity needs beyond the ones the base class provides, and the queries behind them, are the application's own. The entity types the class is typed on are generated separately.
Remaining work: The project's own entities are not covered by that layer. What the README states is where the external-service classes go; the calls inside them are the application's.
The custom logic of a CAP service written in TypeScript sits in one class per entity rather than in a single service implementation file, and each class's methods still reach the framework as the before, on and after handlers for that entity.
Covers how one service's handlers are divided up and what makes a method a handler. What the handlers then do, the generated types they use, which is typing, and how the project is transpiled or built are not this outcome.
Remaining work: The service implementation keeps one place that lists the handler classes, the CDSDispatcher constructor, so a new class is added there as well as written. The decorator compiler options and the generated entity types the decorators take are the project's own setup.
Remaining work: The service implementation still calls registerHandlers in its init(), and the entity a class belongs to is returned by a method on the class rather than declared to the framework.
Remaining work: The folder and file names carry the binding, so renaming a service or an entity in the model means moving or renaming files. The README read today does not state which method names a handler class uses.
Conditions: reflect-metadata is installed and imported before the package is used emitDecoratorMetadata and experimentalDecorators are set in the project's tsconfig.json
Remaining work: The TypeScript decorator setup is the project's: reflect-metadata imported before anything else, and emitDecoratorMetadata and experimentalDecorators set in tsconfig.json. The README names no @sap/cds version it was built against.
Remaining work: Not established. A reader would have to read the published package to find out what it binds and how.
It calls the OpenAI API directly with a key in the environment. It was written in early 2023 and last touched in May 2023, which is before SAP AI Core and the CAP LLM plugins existed — so read it for the shape of the application, not for how a CAP service should reach a model today.
cds watch detects TypeScript mode from a tsconfig.json and runs cds-tsx itself, so a TypeScript project is started with the same command as a JavaScript one. Until then the dev loop needed its own command.
Setup steps that tell a reader to run cds-tsx watch or cds-ts watch to start a TypeScript project. The release note's own sentence is that this is not necessary anymore.
Before this, deriving TypeScript types from a CDS model meant a separate community CLI run as an extra build step — cds2types was the one most people reached for, alongside hand-written declarations. In July 2023 cds-typer went open source under the cap-js GitHub org and onto npm as @cap-js/cds-typer, already supporting the array-of/many syntax and enums by the time of that announcement, giving the framework a maintained, official generator for the first time.
Setup guidance from 2020-2022 that reaches for cds2types, hand-written .d.ts files or another community fork to get typed entities out of a CDS model. That gap is what cds-typer closed in mid-2023; what is left open, and what this capability records, is the shape of the code around the generated types — dispatchers, repositories, controller-service-repository layering — which the core still has no opinion on.
These are the questions used to compare what the artifacts do. Values come from their documentation and may apply to a particular ecosystem or runtime. Each recorded value in the comparison opens its statement and sources.
capability:typescript-patterns