Build toolBuild tooltypeRuns at build time. Nothing of it ships in the deployed application.See every one →What this type is →by SAPby SAPoriginPublished by SAP itself. A visible facet, never an input to a reading — a dormant official plugin reads exactly like a dormant independent one.See every one →
TypingCAPTypingcapabilityMaking the model visible to the compiler — generated types for entities and events so a rename breaks the build rather than production.
@sap/cds≥ 8@sap/cdsartifactThe peer range, as published.
Who is behind it
SAP Cloud Application Programming ModelSAP Cloud Application Programming ModelOrganisationMaintains this In the atlas: maintains 34@cap-jsmaintainerJohannes VogtPersonContributes to this In the atlas: maintains 1, contributes to 28, wrote 10@AkatuoroOlena VyshnevskaPersonContributes to this In the atlas: contributes to 2@alyonavyshnevskaChristian GeorgiPersonContributes to this In the atlas: maintains 1, contributes to 53@chgeoDaniel HutzelPersonContributes to this In the atlas: contributes to 32, wrote 3@danjoaDaniel O'GradyPersonContributes to this In the atlas: contributes to 10@daogradyGuilherme DellagustinPersonContributes to this In the atlas: contributes to 27@dellagustin-sapOlegs BugrovsPersonContributes to this In the atlas: contributes to 1@GoldSuccHeiko WitteborgPersonContributes to this In the atlas: contributes to 18@hm23Jörg MannPersonContributes to this In the atlas: contributes to 4@joergmannJohannes VogelPersonContributes to this In the atlas: contributes to 25@johannes-vogel18 contributors
What it declares
Every artifact
Type
Build tool
Origin
By SAP
Runtime
Node.js
declared
As a build tool
Declared for
>=8
declared, the peer range, as published
Distributed through
does not say
declared, How the tool is added to a project, as its documentation says.
Connections2
Group by
NodeRelationConditionBasis
Functional1
TypingTypingcapabilityGenerated types that make the model visible to the compilerSAP and community, unassessed
→provides
Generates TypeScript definitions from a CDS model, a singular and a plural type per entity, for TypeScript projects and for JavaScript projects with checkJs.
provides Typing
Functional, stated
For
Generates TypeScript definitions from a CDS model, a singular and a plural type per entity, for TypeScript projects and for JavaScript projects with checkJs.
Basis
“Per default, all properties of emitted types are set to be optional. This reflects how entities can be partial in handlers.”CDS Typer, checked “The cds-typer package offers a way to derive TypeScript definitions from a CDS model to give you enhanced code completion and a certain degree of type safety when implementing services.”Using TypeScript, checked
stated
provides Typing
Functional, stated
For
Generates TypeScript definitions from a CDS model, a singular and a plural type per entity, for TypeScript projects and for JavaScript projects with checkJs.
Basis
“Per default, all properties of emitted types are set to be optional. This reflects how entities can be partial in handlers.”CDS Typer, checked “The cds-typer package offers a way to derive TypeScript definitions from a CDS model to give you enhanced code completion and a certain degree of type safety when implementing services.”Using TypeScript, checked
Generated types that make the model visible to the compiler
Technical1
cap-cds-typercap-cds-typersampleCAP service in TypeScript using types from @cap-js/cds-typerindependent, cap
←needed by
The generated model the handlers import from: the project declares the generator and maps `#cds-models/*` to its output in package.json and again in tsconfig.json.
needed by cap-cds-typer
Technical, derived, through inverted from its requires edge
For
The generated model the handlers import from: the project declares the generator and maps `#cds-models/*` to its output in package.json and again in tsconfig.json.
Technical, derived, through inverted from its requires edge
For
The generated model the handlers import from: the project declares the generator and maps `#cds-models/*` to its output in package.json and again in tsconfig.json.
Derived from the package name. No recipe recorded; the README has the configuration.
Learn more2
Readings
Exploring the TypeScript Ecosystem with @cap-js/cds-typer, cds-ts, and node-ts Part - 2Exploring the TypeScript Ecosystem with @cap-js/cds-typer, cds-ts, and node-ts Part - 2blogPart two takes the TypeScript project from part one to Cloud Foundry: cds add mta, then the parts of the generated descriptor the author singles out as needing attention for a TypeScript build rather than a JavaScript one. The pair together is the whole path — typed model locally, then deployed — which is where a typing walkthrough usually stops short.satya-dev, published 2024-07-19satya-dev, SAP Community
Exploring the TypeScript Ecosystem with @cap-js/cds-typer, cds-ts, and node-tsExploring the TypeScript Ecosystem with @cap-js/cds-typer, cds-ts, and node-tsblogPart one of two: a bookshop project built in TypeScript from cds init, with cds-typer added as a development dependency and the surrounding tools — cds-ts and node-ts — put in place so the project runs locally. A setup walkthrough rather than an argument about typing, and it stops at the point where the application works on a laptop; deployment is part two.satya-dev, published 2024-07-08satya-dev, SAP Community
What changed
v0.40.0
output_d_ts_files defaults to true: the generated types are ambient .d.ts declaration files instead of .ts files. Setting it to false restores the old output.
Makes stale:
Build setups written around cds-typer emitting .ts files that TypeScript then compiles.
3 earlier
v0.34.0
use_entities_proxy, which allows static imports of the generated entity classes, defaults to true; setting it to false restores the earlier behaviour.
Makes stale:
Advice to switch on use_entities_proxy before importing generated entities statically.
v0.33.0
cds.Binary is typed as Buffer and cds.LargeBinary as Readable, matching @cap-js/hana and @cap-js/sqlite; legacy_binary_types: true restores the old types.
Makes stale:
Handler code typed against the earlier generated types for cds.Binary and cds.LargeBinary.
v0.11.0
compileFromCSN is no longer exported from the package's programmatic API.
Certain language features of CDS can not be represented in TypeScript.
Trying to generate types for models using these features will therefore result in incorrect or broken TypeScript code.
Changing Types
While the following is valid CDS, there is no TypeScript equivalent that would allow the type of an inherited property to change (TS2416).
entity A { foo: Integer};entity B: A { foo: String}
Support, Feedback, Contributing
This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.
Code of Conduct
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.
Licensing
Copyright 2022-2022 SAP SE or an SAP affiliate company and cds-typer contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.
inline enum JS assignments (e.g. Entity.prop ??= {...}) are no longer emitted using the aspect's singular name as the left-hand side. Aspects have no runtime JS value, so such assignments caused a ReferenceError at startup. The assignments are now correctly emitted on the concrete entity that includes the aspect.
Events with dotted names (e.g. service S { event X.Y : {...} }) now generate a properly namespaced class namespace X { class Y } instead of producing duplicate top-level identifiers.
Event names now use the service-relative name (e.g. 'X.Y' without preceeding S), matching the name the CDS runtime uses when registering and emitting such events.
Entity elements of named struct types used within CDS aspects are now correctly flattened when using --inlineDeclarations flat.
output_d_ts_files now defaults to true and emits proper ambient .d.ts declaration files instead of merely renaming .ts output files. Plain .ts files are treated as source by TypeScript and other build tools, which caused them to be compiled and their .js output to silently overwrite the runtime module exports generated by cds-typer. Projects with strict tsconfig.json settings will benefit from this change, as .d.ts files do not require special handling in cds build or development scripts. Set to false to restore the old behaviour.
Deprecated
Removed
Fixed
Entities with name conflicts with any of their ancestors now have their aspect name generated properly again
Fixed sporadic [Object object] appearing in log output
Removed, Deprecated, Security, Features 2, Changed, Fixes 1
Notes
Added
Added flag cds.env.typer.branded_primitive_types for branding CDS type definitions aliasing primitive TS types
Added support for non-ASCII identifiers in .cds files. Non-ASCII characters in identifiers are sanitised to valid TypeScript names. Identifiers consisting entirely of non-ASCII characters (e.g., Kanji) are replaced with random hashes. All affected identifiers are exported under their sanitised/hashed name and also as an alias preserving the original name. To use the original name, import it with import ... as '...' syntax.
Changed
Deprecated
Removed
Fixed
Association keys pointing to entities with inline enum types are now correctly typed in service projections across namespace boundaries
Removed, Deprecated, Security, Features 1, Changed 2, Fixes
Notes
Added
Improved performance of repeated cds-typer runs by introducing an option to cache CDS model between runs. By default, typer will only regenerate the files if the model has changed between runs, using blake2s256 as algorithm. The used version of cds-typer is included in the hash and will therefore be version-specific.
Changed
[breaking] The config use_entities_proxy (allowing for static imports) is now set to true as default. You can set it to false to revert to the old behaviour.
Running cds watch will trigger cds-typer "*" before the initial startup
Removed, Deprecated, Security, Features 2, Changed 2, Fixes
Notes
Added
Support new cds.Map type, which is emitted as {[key:string]: unknown}. The most appropriate type would in fact be {[key:string]: any}, which would also allow any and all keys. But would also cause issues with strict project configurations. Therefore, to effectively use cds.Map, users will have to cast the unknowns to the effective type they expect.
Introduce cds.env.typer.build_task to allow disabling the typescript build task shipped with cds-typer by setting it to false
Changed
[breaking] The types cds.Binary and cds.LargeBinary are now generated as Buffer and Readable respectively to reflect the behaviour of the new database packages @cap-js/hana and @cap-js/sqlite. You can switch back to the old behaviour by adding legacy_binary_types: true to your project configuration.
CHANGELOG.md and LICENSE files are no longer part of the npm package.
[breaking] when running cds-typer in a CAP project, the default for the outputDirectory option will be ./@cds-models instead of ./. This default takes the lowest precedence after setting it in the project's cds.env, or explicitly as CLI argument.
Fixed
cds-typer no longer ignores the selected outputDirectory, which would also cause an issue during build
[breaking] cds-typer now tries to automatically detect whether it has to generate ESM or CommonJS in the emitted index.js files. This behaviour can be overridden via the --targetModuleType option. If you rely on these generated index.js files to be CJS despite your project being of ESM type, you need to manually tell cds-typer to generate CJS files!
Fixed
The static .keys property now properly reels in key types from inherited classes.
Schema definition for cds.typer options in package.json and .cdsrc-*.json files
Added a static elements property to all entities, which allows access to the LinkedDefinitions instance of an entity's elements
Schema definition for typescript cds build task.
.drafts property of any entity E is now of type DraftOf<E>, or DraftsOf<E> for plurals, respectively. This type exposes dditional properties that are available on drafts during runtime.
Fixed
Entity elements of named structured types are flattened when using the option --inlineDeclarations flat
override modifier on .kind property is now only generated if the property is actually inherited, satisfying strict tsconfig.jsons
Properly support mandatory (not null) action parameters with array of types
Static property .drafts is only create for entity classes that are actually draft enabled
Any configuration variable (via CLI or cds.env) can now be passed in snake_case in addition to camelCase
Action parameters are now generated as optional by default, which is how the runtime treats them. Mandatory parameters have to be marked as not null in CDS/CDL, or notNull in CSN.
Fixed
Fix build task for projects with spaces
Fix a bug where cds-typer would produce redundant type declarations when the model contains an associations to another entity's property
Reintroduce default value '.' for --outputDirectory
Added a static .keys property in all entities. That property is dictionary which holds all properties as keys that are marked as key in CDS
Added a CLI option --useEntitiesProxy. When set to true, all entities are wrapped into Proxy objects during runtime, allowing top level imports of entity types.
Added a static .kind property for entities and types, which contains 'entity' or 'type' respectively
Apps need to provide @sap/cds version 8.2 or higher.
Apps need to provide @cap-js/cds-types version 0.6.4 or higher.
Typed methods are now generated for calls of unbound actions. Named and positional call styles are supported, e.g. service.action({one, two}) and service.action(one, two).
Action parameters can be optional in the named call style (service.action({one:1, ...})).
Actions for ABAP RFC modules cannot be called with positional parameters, but only with named ones. They have 'parameter categories' (import/export/changing/tables) that cannot be called in a flat order.
Services now have their own export (named like the service itself). The current default export is not usable in some scenarios from CommonJS modules.
Enums and operation parameters can have doc comments
Declaring a type alias on an enum in cds now also exports it on value level in the resulting type
Fixed
Classes representing views and projections will no longer carry ancestry to avoid clashes thereof with aliases fields
Changed
All properties are now preceeded with the declare modifier to pass strict tsconfigs using useDefineForClassFields or noImplicitOverride
The static actions property of generated classes now includes the types from all inherited classes to also suggest actions defined in a base entity/aspect/type.
Suppressed an error that would incorrectly point out naming clashes when an entity was named in singular inflection in the model
CDS aspects now also generate a aspect-function in singular inflection, similar to how entities do
Changed
Aspects generate named classes again so that tooltips will show more meaningful provenance for properties
The TypeScript task for cds build no longer looks for tsconfig.json to determine if the project has TS nature and instead checks the dependencies in the project's package.json for an occurrence of typescript
Fixed a bug where keys would sometimes inconsistently become nullable
Changed
Logging now internally uses cds.log and pipes output into the cds-typer logger, which can be configured via cds.env in addition to explicitly passing a --logLevel parameter to CLI. Users now have to use the levels defined in cds.log.levels. The formerly valid levels WARNING, CRITICAL, and NONE are now deprecated and automatically mapped to valid levels for now.
Added IEEE754Compatible flag which, when set to true, generates decimal fields as (number | string) instead of number. This flag will be removed in the long run
Added plugin to cds build TypeScript projects. Can be explicitly called using cds build --for typescript
Changed
Types representing CDS events are now only declared to avoid having to make their properties optional
Singular forms in generated index.js files now contain a .is_singular property as marker for distinguished handling of singular and plural in the runtime
Parameters passed to the CLI now take precedence over configuration contained in the typer section of cds.env
Fixed
Entities ending with an "s" are no longer incorrectly truncated within extends-clauses
Entity names prefixed with their own namespace (e.g. Name.Name, Name.NameAttachments) are not stripped of their name prefix
Types for actions and functions now expose a .kind property which holds the string 'function' or 'action' respectively
Added the CdsDate, CdsDateTime, CdsTime, CdsTimestamp types, which are each represented as a string.
Plural types can now also contain an optional numeric $count property
Changed
Empty .actions properties and operations without parameters are now typed as Record<never, never> to make it clear they contain nothing and also to satisfy overzealous linters
Fixed
Composition of aspects now properly resolve implicit typeof references in their properties
Importing an enum into a service will now generate an alias to the original enum, instead of incorrectly duplicating the definition
Returning entities from actions/ functions and using them as parameters will now properly use the singular inflection instead of returning an array thereof
Aspects are now consistently named and called in their singular form
Only detect inflection clash if singular and plural share the same namespace. This also no longer reports sap.common as erroneous during type creation
Resolving @sap/cds will now look in the CWD first to ensure a consistent use the same CDS version across different setups
Types of function parameters starting with cds. are not automatically considered builtin anymore and receive a more thorough check against an allow-list
Improved support for projections, including projections on inline definitions, and on views, as well as support for explicit exclusion and selection of properties
Changed
[breaking] CDS type definitions will not be inflected. Whatever inflection you define them in will be assumed treated as a singular form and will not receive a plural form anymore
Changed default log level from NONE to ERROR. See the doc to manually pass in another log level for cds-typer runs
Name collisions between automatically generated foreign key fields (.…_ID, .…_code, etc.) with explicitly named fields will now raise an error
Generate CDS types that are actually structured types as if they were entities. This allows the correct representation of mixing aspects and types in CDS inheritance, and also fixes issues with inline enums in such types
Fixed
Externally defined enums can now be used as parameter types in actions
Inline enums are now available during runtime as well
Inline enums can now be used as action parameter types as well. These enums will not have a runtime representation, but will only assert type safety!
Arrays of inline enum values can now be used as action parameters too. But they will only be represented by their enclosing type for now, i.e. string, number, etc.
Foreign keys of projection entities are now propagated as well
Autoexposed entities in services are now also generated
Each generated class now contains their original fully qualified name in a static .name property
Inline enums that are defined as literal type of properties are now supported as well (note: this feature is experimental. The location to which enums are generated might change in the future!)
Fixed
Fixed an error when an entity uses type of on a property they have inherited from another entity
Fixed an error during draftability propagation when defining compositions on types that are declared inline
Removed
compileFromCSN is no longer part of the package's API
Actions and functions are now attached to a static .actions property of each generated class. This reflects the runtime behaviour better than the former way of generating instance methods
Facilitate strict property checks. Note: checkJs: true must be present in the project's jsconfig.json or tsconfig.json respectively for this feature to become effective
Added
Support for array of syntax
Fixed
Generate string type for date-related types in CDS definitions
Generate Buffer | string type for the CDS type LargeBinary
TypingTypingcapabilityMaking the model visible to the compiler — generated types for entities and events so a rename breaks the build rather than production.SAP and community, unassessed
com.sap.cds:cds-maven-plugincom.sap.cds:cds-maven-pluginbuild-toolThe Maven plugin that runs CDS build steps in a CAP Java project: compiling the model, generating typed Java accessor interfaces and adding facets to an existing project.sap official, capMaven plugin running CDS build steps in a CAP Java project
@cap-js/cds-types@cap-js/cds-typespackageType definitions for the CAP Node.js SDK.sap official, capType definitions for the CAP Node.js SDK
cds-internal-toolcds-internal-toolpackageReusable internals for people writing CAP extensions — annotation helpers, current cds runtime types, module resolution, reflection utilities and type assertions.independent, capReusable internals for authors of CAP extensions
