@dxfrontier/cds-ts-dispatcher

Decorator-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.

GitHub15 ★

npm17/wk

Facts

Latestv6.1.0Released2026-08-06Last push2026-09-25LicenceMIT

Where it sits

Lives in

CAP

Provides

TypeScript patterns CAP

Flavors

Node.js

Requires

@sap/cds^10

Who is behind it

dx frontier GmbHmaintainer3 contributors

What it declares

Sources

Every artifact

Type: Package
Origin: Independently maintained

As a package

Declared for: ^10
declared, the peer range, as published
Where it runs: does not say
declared, Where the library runs once installed: inside its host (loaded into the CAP application, installed into the ABAP system, loaded by the UI5 application), in a program of your own, or only at build time.
Distributed through: npm
declared, How it is installed, as its documentation tells a user to get it., read 2026-10-18npm install @dxfrontier/cds-ts-dispatcher — @dxfrontier/cds-ts-dispatcher — README, 2026-10-18

For typeScript patterns

Supports: Dependency injectionDraft events
stated by its maintainer“Dependency injection: The `@Inject` decorator is utilized as a `field-level` decorator and allows you to inject dependencies into your classes.” dxfrontier/cds-ts-dispatcher — README, @Inject, 2026-10-15“Draft events: If `@odata.draft.enabled: true` to manage event handlers for draft version you can use” dxfrontier/cds-ts-dispatcher — README, draft decorators, 2026-10-15
How handlers bind: decorators
stated by its maintainer“Use @BeforeCreate(), @BeforeRead(), @BeforeUpdate(), @BeforeDelete() to register handlers to run before `.on` handlers, frequently used for `validating user input.`” dxfrontier/cds-ts-dispatcher — README, Before, 2026-10-15
Layers it names: handlersservice logicpersistence
stated by its maintainer“We recommend adhering to the Controller-Service-Repository design pattern using the following folder structure:” dxfrontier/cds-ts-dispatcher — README, Architecture, 2026-10-15

property statedstated nonot said

Tasks this contributes to3Beta

TypeScript patterns3

Handle a draft's own events apart from the active entity'sA 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.Node.jsCovers, under conditionsdraft decorators

What it does

Carries a second set of decorators for the draft version of an entity's events beside the active-entity ones, so a method is marked as a draft handler where it is written rather than registered against a drafts entity by hand.

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.

All options on the TypeScript patterns page →

Keep data access out of a CAP service's handlersThe 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.Node.jsCoverslayering and injection

What it does

Names the layer and puts the object in the handler's hands: its documentation recommends Controller-Service-Repository, gives the persistence layer the @Repository class decorator, and @Inject places a repository or a service class into a field of another class.

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.

All options on the TypeScript patterns page →

Split one CAP service implementation into a class per entityThe 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.Node.jsCovershandler registration from decorators

What it does

A class decorated with @EntityHandler is the place one entity's handlers go, and the method decorators beside it, @BeforeCreate, @BeforeRead and the rest, register what srv.before and srv.on would have. A CDSDispatcher instance in the service implementation is given the handler classes.

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.

All options on the TypeScript patterns page →

Connections1

Group by

NodeRelationBasis

Functional1

TypeScript patterns

provides

stated

How an application is arranged once written in TypeScript

Download

Install

npm add @dxfrontier/cds-ts-dispatcher

Derived from the package name. No recipe recorded; the README has the configuration.

Learn more2

Readings

SAP CAP: Controller - Service - Repository architectureDaniel Dragolea, SAP Community2024-04-22
CDS-TS-Dispatcher: Simplifying SAP CAP TypeScript DevelopmentDaniel Dragolea, SAP Community2023-11-13

README

quoted from dxfrontier/cds-ts-dispatcher under MIT, read 2026-10-26

dxfrontier/cds-ts-dispatcher/README.mdthe maintainer’s wordsOn GitHub

CDS-TS-Dispatcher

The goal of CDS-TS-Dispatcher is to significantly reduce the boilerplate code required to implement Typescript handlers provided by the SAP CAP framework.

Prerequisites
Installation
Migration guides
Usage
Deployment to BTP using MTA
Best practices & tips
Samples
Contributing
License
Authors

Prerequisites

Install @sap/cds-dk, typescript, ts-node globally:

npm i -g @sap/cds-dk typescript ts-node tsx

Installation

`Option 1 :` Install CDS-TS-Dispatcher - `New project`

Use the following steps if you want to create a new SAP CAP project.

Create new folder :

mkdir project
cd project

Initialize the CDS folder structure :

cds init

Add TypeScript and CDS-Typer to your npm package.json:

cds add typescript

Add CDS-TS-Dispatcher to your npm package.json :

npm install @dxfrontier/cds-ts-dispatcher

It is recommended to use the following tsconfig.json properties:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowJs": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": false,
    "forceConsistentCasingInFileNames": true,
    "allowSyntheticDefaultImports": true,

    "strict": true,

    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,

    "target": "esnext",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",

    "outDir": "./gen/srv",
    "rootDir": ".",

    "paths": {
      "#cds-models/*": ["./@cds-models/*/index.ts"]
    }
  },
  "include": ["./srv", "./@dispatcher"]
}

Install packages

npm install

Run the CDS-TS server

cds-ts w

Important

CDS-TS-Dispatcher uses @sap/cds, @sap/cds-dk version 9.

If you're using @sap/cds, @sap/cds-dk version 8 then install npm install @dxfrontier/cds-ts-dispatcher@4.

packages	version
@cap-js/asyncapi	1.0.1
@cap-js/cds-typer	0.24.0
@cap-js/cds-types	0.6.4
@cap-js/openapi	1.0.4
@cap-js/sqlite	1.7.3
`@sap/cds`	`8.1.0`
@sap/cds-compiler	5.1.2
`@sap/cds-dk (global)`	`8.0.2`
@sap/cds-fiori	1.2.7
@sap/cds-foss	5.0.1
@sap/cds-lsp	8.0.0
@sap/cds-mtxs	1.18.2
@sap/eslint-plugin-cds	3.0.4
Node.js	v22.4.1

packages	version
@cap-js/asyncapi	1.0.3
@cap-js/cds-typer	0.35.0
@cap-js/cds-types	0.11.0
@cap-js/db-service	2.1.1
@cap-js/openapi	1.2.3
@cap-js/sqlite	2.0.1
`@sap/cds`	`9.0.3`
@sap/cds-compiler	6.0.12
`@sap/cds-dk (local)`	`9.0.4`
`@sap/cds-dk (global)`	`9.0.4`
@sap/cds-fiori	2.0.1
@sap/cds-mtxs	3.0.1
Node.js	v22.14.0
home	/Users/dragolea/Developer/abs-projects/cds-ts-dispatcher/node_modules/@sap/cds

packages	version
@cap-js/cds-types	0.18.0
@cap-js/db-service	3.0.1
@cap-js/sqlite	3.0.2
`@sap/cds`	`10.0.3`
@sap/cds-compiler	7.0.2
`@sap/cds-dk`	`10.0.5`
Node.js	v22.14.0
home	/Users/dragolea/Developer/abs-projects/cds-ts-dispatcher/node_modules/@sap/cds

Method	Parameters	Description
1. EntityHandler(`entity`: CDSTyper)	Must be a `CDS-Typer` generated class	It ensures that all handlers within the class operate with the specified `entity context`.
2. EntityHandler(`entity`: `'*'`)	A wildcard `'*'` indicating all entities	It ensures that all handlers within the class operate with a generic context indicating that registered events will be triggered for all `all entities` (`active entities` and `draft entities`) Excluded will be @OnAction(), @OnFunction(), @OnEvent(), @OnError() as these actions belongs to the Service itself.

Parameters	Decorator	Description
`results, req`	`@AfterRead`	An array of type `MyEntity[]` and the `Request`.
`result, req`	`@AfterUpdate` `@AfterCreate`	An object of type `MyEntity` and the `Request`.
`deleted, req`	`@AfterDelete`	A `boolean` indicating whether the instance was deleted and the `Request`.

Option	Type	Default	Description
`limit`	`number`	(required)	Maximum number of invocations allowed per window. Must be `>= 1`.
`window`	`number` (ms)	(required)	Fixed window length in milliseconds. Must be `>= 1`.
`by`	`'user' \| 'tenant'`	`'user'`	Counter key source: `'user'` keys by `req.user.id` (fallback `'anonymous'`), `'tenant'` keys by `req.tenant` (fallback `'no-tenant'`).

Action	Description	Options
contains	Check if the string contains the seed.	ignoreCase: boolean \| undefined; default : false minOccurrences: number \| undefined; default 1
equals	Check if the string matches the comparison.
matches	Check if the string matches the pattern.
startsWith	Checks if the string starts with the given `target` string.
endsWith	Checks if the string ends with the given `target` string.
isMailtoURI	Check if the string is a Mailto URI format.	allow_display_name: If set to `true`, the validator will also match `Display Name <email-address>`. Default: false require_display_name: If set to `true`, the validator will reject strings without the format `Display Name <email-address>`. Default: false allow_utf8_local_part: If set to `false`, the validator will not allow any non-English UTF8 character in the email address' local part. Default: true require_tld: If set to `false`, email addresses without a TLD in their domain will also be matched. Default: true ignore_max_length: If set to `true`, the validator will not check for the standard max length of an email. Default: false allow_ip_domain: If set to `true`, the validator will allow IP addresses in the host part. Default: false domain_specific_validation: If set to `true`, some additional validation will be enabled, e.g., disallowing certain syntactically valid email addresses that are rejected by GMail. Default: false host_blacklist: An array of strings. If the part of the email after the `@` symbol matches any string in the array, validation fails. host_whitelist: An array of strings. If the part of the email after the `@` symbol does not match any string in the array, validation fails. blacklisted_chars: A string. If any character in the string appears in the name part of the email, validation fails.
isNumeric	Check if the string contains only numbers.	no_symbols: If set to `true`, the validator will reject numeric strings that feature a symbol (e.g., `+`, `-`, or `.`). _Default: false* locale: An object specifying the locale information for alpha validation.
isTime	Check if the string is a valid time e.g. `23:01:59`.	hourFormat: Specify the hour format to validate. Use `'hour12'` for 12-hour format and `'hour24'` for 24-hour format. Default: 'hour24' mode: Specify the time format to validate. Use `'default'` for HH:MM format and `'withSeconds'` for HH:MM:SS format. Default: 'default'
isLatLong	check if the string is a valid latitude-longitude coordinate in the format `lat,long` or `lat, long`.
isMD5	check if the string is a MD5 hash.
isMimeType	check if the string matches to a valid [MIME type] format.
isPort	check if the string is a valid port number.
isSlug	check if the string is of type slug.
isISBN	check if the string is an [ISBN]	version: "10", "13", 10, 13;
isEmail	check if the string is an email.	Same as `isMailtoURI`
isAlpha	Check if the string contains only letters (a-zA-Z).
isAlphanumeric	Check if the string contains only letters and numbers.
isCreditCard	Check if the string is a credit card.	provider: Specify the credit card provider to validate. Use one of the following: `'amex'`, `'dinersclub'`, `'discover'`, `'jcb'`, `'mastercard'`, `'unionpay'`, `'visa'`, or `''` for any provider. Default: undefined
isCurrency	Check if the string is a valid currency amount.	symbol: The currency symbol to be expected. Default: '$' require_symbol: If set to `true`, the validator will expect the currency symbol to be present. Default: false allow_space_after_symbol: If set to `true`, the validator will allow a space after the currency symbol. Default: false symbol_after_digits: If set to `true`, the currency symbol will be expected after the digits. Default: false allow_negatives: If set to `true`, negative currency values will be allowed. Default: true parens_for_negatives: If set to `true`, negative currency values will be enclosed in parentheses. Default: false negative_sign_before_digits: If set to `true`, the negative sign will be placed before the digits. Default: false negative_sign_after_digits: If set to `true`, the negative sign will be placed after the digits. Default: false allow_negative_sign_placeholder: If set to `true`, the validator will allow a placeholder `-` for negative values. Default: false thousands_separator: The thousands separator to be expected. Default: ',' decimal_separator: The decimal separator to be expected. Default: '.' allow_decimal: If set to `true`, decimal values will be allowed. Default: true require_decimal: If set to `true`, a decimal value will be required. Default: false digits_after_decimal: An array of numbers representing the exact number of digits allowed after the decimal point. Default: [2] allow_space_after_digits: If set to `true`, the validator will allow a space after the digits. Default: false
isDataURI	Check if the string is a data URI format.
isDate	Check if the string is a valid date.	format: A string representing the expected date format. Default: undefined strictMode: If set to `true`, the validator will reject inputs different from the specified format. Default: false delimiters: An array of allowed date delimiters. Default: ['/', '-']
isEmpty	Check if the string has a length of zero.	ignore_whitespace: If set to `true`, whitespace characters will be ignored. Default: false
isIBAN	Check if a string is an IBAN.	whitelist: An array of IBAN countries to whitelist. Default: undefined blacklist: An array of IBAN countries to blacklist. Default: undefined
isIMEI	Check if the string is a valid IMEI.	allow_hyphens: If set to `true`, allows IMEI numbers with hyphens. Default: false
isIP	Check if the string is an IP (version 4 or 6).	`"4", "6", 4, 6;`
isIdentityCard	Check if the string is a valid identity card code.	locale: An array of supported locales for identity cards. Acceptable values: "ar-LY", "ar-TN", "ES", "FI", "he-IL", "IN", "IR", "IT", "LK", "NO", "PL", "TH", "zh-CN", "zh-HK", "zh-TW" or 'any'
isIn	Check if the string is in an array of allowed values.
isJSON	Check if the string is valid JSON (note: uses `JSON.parse`).
isJWT	Check if the string is a valid JWT token.
isLength	Check if the string's length falls in a range.	min: The minimum length allowed for the string. Default: 0 max: The maximum length allowed for the string. Default: undefined
isLowercase	Check if the string is lowercase.
isMobilePhone	Check if the string is a mobile phone number.	strictMode: If set to `true`, the mobile phone number must be supplied with the country code and must start with `+`. Default: false
isPassportNumber	Check if the string is a valid passport number relative to a specific country code.
isPostalCode	Check if the string is a postal code.	"AD", "AT", "AU", "BE", "BG", "BR", "CA", "CH", "CN", "CZ", "DE", "DK", "DZ", "EE", "ES", "FI", "FR", "GB", "GR", "HR", "HU", "ID", "IE", "IL", "IN", "IR", "IS", "IT", "JP", "KE", "KR", "LI", "LT", "LU", "LV", "MX", "MT", "NL", "NO", "NZ", "PL", "PR", "PT", "RO", "RU", "SA", "SE", "SI", "SK", "TN", "TW", "UA", "US", "ZA", "ZM"
isURL	Check if the string is a URL.	protocols: An array of allowed protocols. Default: ['http', 'https', 'ftp'] require_tld: If set to `true`, URLs must have a top-level domain. Default: true require_protocol: If set to `true`, URLs must have a protocol. Default: false require_host: If set to `true`, URLs must have a host. Default: true require_port: If set to `true`, isURL will check if a port is present in the URL. Default: false require_valid_protocol: If set to `true`, URLs must have a valid protocol. Default: true allow_underscores: If set to `true`, underscores are allowed in URLs. Default: false host_whitelist: An array of allowed hosts. host_blacklist: An array of disallowed hosts. allow_trailing_dot: If set to `true`, trailing dots are allowed in URLs. Default: false allow_protocol_relative_urls: If set to `true`, protocol-relative URLs are allowed. Default: false disallow_auth: If set to `true`, authentication credentials in URLs are disallowed. Default: false allow_fragments: If set to `true`, URL fragments are allowed. Default: true allow_query_components: If set to `true`, URL query components are allowed. Default: true validate_length: If set to `true`, URLs will be validated for length. Default: true
isUUID	Check if the string is a UUID (version 1, 2, 3, 4, or 5).
isUppercase	Check if the string is uppercase.
isVAT	Checks that the string is a valid VAT number.
isWhitelisted	Checks if characters appear in the whitelist.
isInt	Check if the string is an integer.	min: to check the integer min boundary max: to check the integer max boundary allow_leading_zeroes: if `false`, will disallow integer values with leading zeroes. Default: true lt: enforce integers being greater than the value provided gt: enforce integers being less than the value provided
isHexadecimal	Check if the string is a hexadecimal number.
isFloat	Check if the string is a float.	min: less or equal max: greater or equal gt: greater than lt: less than locale: FloatLocale
isHash	Check if the string is a hash of export type algorithm.	"md4", "md5", "sha1", "sha256", "sha384", "sha512", "ripemd128", "ripemd160", "tiger128", "tiger160", "tiger192", "crc32", "crc32b"
isEAN	Check if the string is an EAN (European Article Number).
isDecimal	Check if the string represents a decimal number, such as `0.1`, `.3`, `1.1`, `1.00003`, `4.0` etc.	force_decimal: If set to `true`, the validator will only return `true` if the string contains a decimal number. Default: false decimal_digits: Specifies the number of decimal digits allowed. It can be given as a range like `'1,3'`, a specific value like `'3'`, or min like `'1,'`. Default: '1,' locale: The locale to use for number formatting. Default: 'en-US'
isBoolean	Check if a string is a boolean.	loose: If set to `true`, the validator will match a valid boolean string of any case, including ['true', 'True', 'TRUE'], and also 'yes' and 'no'. If set to `false`, the validator will strictly match ['true', 'false', '0', '1']. Default: false
isBIC	Check if a string is a BIC (Bank Identification Code) or SWIFT code.
isBefore	Check if the string is a date that's before the specified date.
isAfter	Check if the string is a date that's after the specified date.

Action	Description
blacklist	Remove characters that appear in the blacklist.
ltrim	Trim characters from the left-side of the input.
rtrim	Trim characters from the right-side of the input.
trim	Trim characters from both sides of the input.
escape	Replace `<`, `>`, `&`, `'`, `"` and `/` with HTML entities.
unescape	Replaces HTML encoded entities with `<`, `>`, `&`, `'`, `"` and `/`.
toLower	Converts string, as a whole, to lower case.
toUpper	Converts string, as a whole, to upper case.
upperFirst	Converts the first character of the string to upper case.
lowerFirst	Converts the first character of the string to lower case.
replace	Replaces matches for pattern in string with replacement. Note: This method is based on String#replace.
truncate	Truncates string if it’s longer than the given maximum string length. The last characters of the truncated, string are replaced with the omission string which defaults to "…".
snakeCase	Snake case (or snakecase) is the process of writing compound words so that the words are separated with an underscore symbol () instead of a space. The first letter is usually changed to lowercase. Some examples of Snake case would be `"foo_bar" or "hello_world".`
kebabCase	Kebab case, also known as "spinal case" or "hyphen case," involves writing compound words in lowercase letters and separating them with hyphens ("-"). For example, the phrase "user settings panel" would be represented as `"user-settings-panel"` in the kebab case.
camelCase	The format indicates the first word starting with either case, then the following words having an initial uppercase letter. `CustomerName, LastName ...`
customFormatter	Apply a custom formatter when standard ones do not satisfy your needs.

What it declares

Every artifact

As a package

For typeScript patterns

Tasks this contributes to3Beta

What it does

Conditions

Remaining work

What it does

Remaining work

What it does

Remaining work

Connections1

Install

Learn more2

README

CDS-TS-Dispatcher

Table of Contents

Prerequisites

Installation

Option 1 : Install CDS-TS-Dispatcher - New project

Option 2 : Install CDS-TS-Dispatcher - Existing TypeScript project

Generate CDS Typed entities

Important

Migration guides

Migration: from @sap/cds v7 to v8

Migration: from @sap/cds v8 to v9

Migration: from @sap/cds v9 to v10

Usage

Architecture

CDSDispatcher

Decorators

Class

@EntityHandler

@ServiceLogic

@Repository

[Optional] - CDS-TS-Repository - BaseRepository

@UnboundActions

@ServerLifecycle

@Use

Field

@Inject

@Inject(CDS_DISPATCHER.SRV)

@Inject(CDS_DISPATCHER.OUTBOXED_SRV)

Parameter

@Req

@Res

@Results / @Result

@Next

@Error

@Jwt

@IsPresent

@IsRole

@IsColumnSupplied

@GetQuery

@GetRequest

@SingleInstanceSwitch

@ValidationResults

@Locale

@Env

@Subject

@Affected

@Data

@Param

@UserInfo

@Tenant

@Diff

@Msg

Method — CRUD, active entity

Before

@BeforeCreate

@BeforeRead

@BeforeUpdate

@BeforeDelete

@BeforeAction

@BeforeBoundAction

@BeforeFunction

@BeforeBoundFunction

@BeforeAll

After

`Option 1 :` Install CDS-TS-Dispatcher - `New project`

`Option 2 :` Install CDS-TS-Dispatcher - `Existing TypeScript project`

`Generate CDS Typed entities`

`Important`

`Migration:` from @sap/cds `v7` to `v8`

`Migration:` from @sap/cds `v8` to `v9`

`Migration:` from @sap/cds `v9` to `v10`

`Architecture`

`CDSDispatcher`

`Decorators`

`[Optional]` - CDS-TS-Repository - BaseRepository

@Inject(`CDS_DISPATCHER.SRV`)

`Before`

`After`

`On`

`Before`

`After`

`On`

`Other draft decorators`