@cap-js/cds-types 0.1.0 → 0.3.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-types",
-  "version": "0.1.0",
+  "version": "0.3.0-beta.1",
   "description": "Type definitions for main packages of CAP, like `@sap/cds`",
   "repository": "github:cap-js/cds-types",
   "homepage": "https://cap.cloud.sap/",
@@ -11,28 +11,43 @@
   ],
   "author": "SAP SE (https://www.sap.com)",
   "license": "SEE LICENSE IN LICENSE",
-  "typings": "apis/cds.d.ts",
+  "typings": "dist/cds-types.d.ts",
   "files": [
-    "apis/",
+    "dist/",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "test": "jest --silent",
-    "api-extractor": "api-extractor run --local --verbose"
+    "rollup": "rm -rf dist/ && mkdir -p etc/ && npx -y @microsoft/api-extractor run --local --verbose && .github/rollup-patch.js",
+    "rollup:on": "npm pkg set typings=dist/cds-types.d.ts && [ -d 'apis' ] && mv -- apis -apis || true",
+    "rollup:off": "npm pkg set typings=apis/cds.d.ts  && [ -d '-apis' ] && mv -- -apis apis || true",
+    "lint": "npx eslint .",
+    "lint:fix": "npx eslint . --fix",
+    "setup": "npm i && npm i file:. --no-save --force",
+    "prerelease:ci-fix": ".github/prerelease-fix.js"
   },
   "peerDependencies": {
-    "@sap/cds": ">=7"
+    "@sap/cds": ">=7 || ^8.0.0-beta"
+  },
+  "dependencies": {
+    "@types/express": "^4.17.21"
   },
   "devDependencies": {
-    "@sap/cds": "^7.4.0",
+    "@eslint/js": "^9.2.0",
+    "@sap/cds": ">=7.5.0",
+    "@stylistic/eslint-plugin-js": "^2.1.0",
+    "@stylistic/eslint-plugin-ts": "^2.1.0",
+    "@types/jest": "^29.5.11",
     "@types/node": "^20",
     "axios": "^1.6.2",
     "chai": "^4.3.10",
+    "eslint": "^9.2.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.1",
-    "typescript": "^5.3.2",
-    "winston": "^3.11.0"
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^8.0.0-alpha.10",
+    "winston": "^3.13.0"
   },
   "jest": {
     "transform": {

package/apis/cds.d.ts

@@ -1,44 +0,0 @@
-export * from './core'
-export * from './server'
-export * from './env'
-export * from './models'
-export * from './services'
-export * from './events'
-export * from './utils'
-export { log, debug } from './log'
-export { test } from './test'
-export * from './cqn'
-
-// FIXME: sort out what needs to be exported from csn/linked and under which namespace
-// export { Association, CSN, Definition, Extension, Element, EntityElements, FQN, kinds } from './csn'
-// export { Definitions, LinkedCSN, LinkedDefinition, LinkedAssociation, LinkedEntity, Filter, Visitor } from './linked'
-
-// API extractor cannot handle export * as ql from './ql', so split it into an import and an export statement
-import * as ql from './ql'
-export { ql }
-export { QLExtensions } from './ql'  // cds-ql.ts test tries to import this from top level? Correct? Or ql.QLExtensions?
-
-// trick to work around "delete" as reserved identifier
-import { Service } from './services'
-declare const delete_: Service['delete']
-export { delete_ as delete }
-
-declare global {
-	// these provide the functionality from SELECT, INSERT, etc in the global facade
-	const SELECT: ql.QL<any>['SELECT']
-	const INSERT: ql.QL<any>['INSERT']
-	const UPSERT: ql.QL<any>['UPSERT']
-	const UPDATE: ql.QL<any>['UPDATE']
-	const DELETE: ql.QL<any>['DELETE']
-	const CREATE: ql.QL<any>['CREATE']
-	const DROP: ql.QL<any>['DROP']
-
-	// and these allow us to use them as type too, i.e. `const q: SELECT<Book> = ...`
-	type SELECT<T> = ql.SELECT<T>
-	type INSERT<T> = ql.INSERT<T>
-	type UPSERT<T> = ql.UPSERT<T>
-	type UPDATE<T> = ql.UPDATE<T>
-	type DELETE<T> = ql.DELETE<T>
-	type CREATE<T> = ql.CREATE<T>
-	type DROP<T>   = ql.DROP<T>
-}

package/apis/core.d.ts

@@ -1,95 +0,0 @@
-import { LinkedAssociation, LinkedEntity, linked } from './linked'
-import * as csn from './csn'
-import { service } from './server'
-
-type Intersect<T extends readonly unknown[]> = T extends [infer Head, ...infer Tail]
-  ? Head & Intersect<Tail>
-  : unknown
-
-// These are classes actually -> using the new() => interface trick
-/**
- * Base class for linked Associations from reflected models.
- * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
- */
-export type Association = new(_?:object) => LinkedAssociation
-/**
- * Base class for linked Compositions from reflected models.
- * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
- */
-export type Composition = new(_?:object) => LinkedAssociation
-/**
- * Base class for linked entities from reflected models.
- * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-entity)
- */
-export type entity = new(_?:object) => LinkedEntity
-export type event = new(_?:object) => linked & csn.struct
-export type type = new(_?:object) => linked & csn.type
-export type array = new(_?:object) => linked & csn.type
-export type struct = new(_?:object) => linked & csn.struct
-
-// infer (query : cqn, model : csn) : LinkedDefinition
-export const builtin: {
-  /**
-   * Base classes of linked definitions from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-builtin-classes)
-   */
-  classes: {
-    Association: Association
-    Composition: Composition
-    entity: entity
-    event: event
-    type: type
-    array: array
-    struct: struct
-    service: service
-  }
-  types: {}
-}
-
-/**
- * Add aspects to a given object, for example:
- *
- * @example
- * ```js
- *    extend (Object.prototype) .with (class {
- *       get foo() { return ... }
- *       bar() {...}
- *    }.prototype)
- * ```
- */
-export function extend<T>(target: T): {
-  with<E extends readonly unknown[]>(...ext: E): T & Intersect<E>
-}
-
-/**
- * Equip a given facade object with getters for lazy-loading modules instead
- * of static requires. Example:
- *
- * @example
- * ```js
- *    const facade = lazify ({
- *       sub: lazy => require ('./sub-module')
- *    })
- * ```
- *
- * The first usage of `facade.sub` will load the sub module
- * using standard Node.js's `module.require` functions.
- */
-export function lazify <T>(target: T) : T
-
-/**
- * Prepare a node module for lazy-loading submodules instead
- * of static requires. Example:
- *
- * @example
- * ```js
- *    require = lazify (module) //> turns require into a lazy one
- *    const facade = module.exports = {
- *       sub: require ('./sub-module')
- *    })
- * ```
- *
- * The first usage of `facade.sub` will load the sub module
- * using standard Node.js's `module.require` functions.
- */
-export function lazified <T>(target: T) : T

package/apis/cqn.d.ts

@@ -1,87 +0,0 @@
-import { entity } from "./csn" // cyclic dependency
-
-// FIXME: a union type would be more appropriate here
-export type Query = Partial<SELECT & INSERT & UPDATE & DELETE & CREATE & DROP & UPSERT>
-
-export type SELECT = {SELECT:{
-	distinct?: true
-	one? : boolean
-	from : source
-	mixin?: {[key:string]: expr}
-	columns? : column_expr[]
-	excluding? : string[]
-	where? : predicate
-	having? : predicate
-	groupBy? : expr[]
-	orderBy? : ordering_term[]
-	limit?: { rows:val, offset:val }
-}}
-
-export type INSERT = {INSERT:{
-	into : ref | name
-	entries : data[]
-	columns : string[]
-	values : scalar[]
-	rows : scalar[][]
-	as : SELECT
-}}
-
-export type UPSERT = {UPSERT:{
-	into : ref | name
-	columns : string[]
-	entries : data[]
-	values : scalar[]
-	rows : scalar[][]
-}}
-
-export type UPDATE = {UPDATE:{
-	entity : ref | name
-	data : { [key:string] : expr }
-	where? : predicate
-}}
-
-export type DELETE = {DELETE:{
-	from : ref | name
-	where? : predicate
-}}
-
-export type CREATE = {CREATE:{
-	entity : entity | name
-	as: SELECT
-}}
-
-export type DROP = {DROP:{
-	entity : name
-	table: ref
-	view: ref
-}}
-
-/** @private */
-type scalar = number | string | boolean | null
-/** @private */
-type data = Record<string,any>
-/** @private */
-type name = string
-/** @private */
-type source = ( ref | SELECT ) & { as?: name, join?:name, on?:xpr }
-export type column_expr = expr & { as?: name, cast?:any, expand?: column_expr[], inline?: column_expr[] }
-export type predicate = _xpr
-/** @private */
-type ordering_term = expr & { sort?: "asc"|"desc", nulls?: "first"|"last" }
-
-export type expr = ref | val | xpr | function_call | SELECT
-/** @private */
-type ref = {ref:( name & { id?:string, where?:expr, args?:expr[] } )[]}
-/** @private */
-type val = {val:any}
-/** @private */
-type xpr = {xpr:_xpr}
-/** @private */
-type _xpr = ( expr | operator ) []
-/** @private */
-type operator = string
-/** @private */
-type function_call = {func: string, args: {[key: string]: unknown}[]}
-
-export type enum_literal = {"#": string}
-export type expr_literal = {"=": string}

package/apis/csn.d.ts

@@ -1,117 +0,0 @@
-import { SELECT, ref, predicate } from './cqn'
-
-/**
- * A parsed CDS model in CSN object notation.
- */
-export interface CSN {
-  /**
-   * The assigned namespace. If parsed from multiple sources,
-   * this is the topmost model's namespace, if any, not the
-   * ones of imported models.
-   */
-  namespace?: string
-
-  /**
-   * The list of usings in this parsed model. Not available after
-   * imports have been resolved into a merged model.
-   */
-  requires?: string[]
-
-  /**
-   * All definitions in the model including those from imported models.
-   */
-  definitions?: Record<FQN, Definition>
-
-  /**
-   * All extensions in the model including those from imported models.
-   * Not available after extensions have been applied.
-   */
-  extensions?: Extension[]
-
-  /**
-   * The names of the files from which this model has been loaded.
-   */
-  $sources?: string[]
-}
-
-/**
- * The fully-quality name of a definition.
- */
-export type FQN = string
-
-/**
- * Definitions are the central elements of a CDS model.
- */
-export type Definition = context & service & type & struct & entity & Association
-// NOTE: If we use & instead of | CSN.definitions values would be reduced to <never>
-
-/**
- * Extensions capture `extend Foo with { ... }` directives.
- */
-export type Extension = {
-  extend: FQN
-  elements?: { [name: string]: Element }
-  includes?: FQN[]
-}
-
-export type Element = type & struct & Association
-
-export type kinds = 'type' | 'entity' | 'event' | 'service' | 'context' | 'struct'
-
-export interface any_ { kind?: kinds }
-export interface context extends any_ { }
-export interface service extends any_ { }
-
-export interface type extends any_ {
-  type?: FQN
-  items?: type
-}
-
-export interface struct extends type {
-  /**
-   * References to definitions to be included.
-   * Not available after extensions have been applied.
-  */
-  includes?: FQN[]
-  elements: { [name: string]: Element }
-}
-
-export interface entity extends Omit<struct,'elements'> {
-  /**
-   * Entities with a query signify a view
-   */
-  query?: SELECT
-  /**
-   * Elements of entities may have additional qualifiers
-   */
-  elements : EntityElements
-  // REVISIT: following should move to LinkedCSN
-  keys: { [name: string]: Definition }
-  drafts: entity
-}
-
-export type EntityElements = {
-    [name:string]: Element & {
-        key? : boolean
-        virtual? : boolean
-        unique? : boolean
-        notNull? : boolean
-    }
-}
-
-export interface Association extends type {
-  type: 'cds.Association' | 'cds.Composition'
-  target: FQN
-  /**
-   * The specified cardinality. to-one = `{max:1}`, to-many = `{max:'*'}`
-   */
-  cardinality?: { src?: 1; min?: 1 | 0; max?: 1 | '*' }
-  /**
-   * The parsed on condition in case of unmanaged Associations
-   */
-  on?: predicate
-  /**
-   * The optionally specified keys in case of managed Associations
-   */
-  keys?: (ref & { as: string })[]
-}

package/apis/env.d.ts

@@ -1,22 +0,0 @@
-/**
- * Access to the configuration for Node.js runtime and tools.
- * The object is the effective result of configuration merged from various sources,
- * filtered through the currently active profiles, thus highly dependent on the current working
- * directory and process environment.
- */
-export const env : {
-    build: any,
-    hana: any,
-    i18n: any,
-    mtx: any,
-    requires: any,
-    folders: any,
-    odata: any,
-    query: any,
-    sql: any
-} & { [key: string]: any }  // to allow additional values we have not yet captured
-
-export const requires: any
-export const version: string
-export const home: string
-export const root: string

package/apis/events.d.ts

@@ -1,105 +0,0 @@
-import { LinkedDefinition } from './linked'
-import { Query } from './cqn'
-import { ref } from './cqn'
-import * as express from 'express'
-
-
-/**
- * Represents the invocation context of incoming request and event messages.
- * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
- */
-export class EventContext {
-  constructor(properties:{event:string, data?:object, query?:object, headers?:object});
-  http?: {req: express.Request, res: express.Response}
-  tenant: string
-  user: User
-  id: string
-  locale: `${string}_${string}`
-  timestamp: Date
-  features?: { [key: string]: boolean }
-}
-
-/**
- * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
- */
-export class Event extends EventContext {
-  event: string
-  data: any
-  headers: any
-}
-
-/**
- * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
- */
-export class Request extends Event {
-  params: (string | {})[]
-  method: string
-  path: string
-  target: LinkedDefinition
-  /**
-   * Shortcut to {@link Request.target | target (entity) name}
-   * @see https://cap.cloud.sap/docs/node.js/events#req-entity
-   */
-  entity: string
-  query: Query
-  subject: ref
-
-  reply(results: any): void
-
-  notify(code: number, message: string, target?: string, args?: any[]): Error
-  info(code: number, message: string, target?: string, args?: any[]): Error
-  warn(code: number, message: string, target?: string, args?: any[]): Error
-  error(code: number, message: string, target?: string, args?: any[]): Error
-  reject(code: number, message: string, target?: string, args?: any[]): Error
-
-  notify(code: number, message: string, args?: any[]): Error
-  info(code: number, message: string, args?: any[]): Error
-  warn(code: number, message: string, args?: any[]): Error
-  error(code: number, message: string, args?: any[]): Error
-  reject(code: number, message: string, args?: any[]): Error
-
-  notify(message: string, target?: string, args?: any[]): Error
-  info(message: string, target?: string, args?: any[]): Error
-  warn(message: string, target?: string, args?: any[]): Error
-  error(message: string, target?: string, args?: any[]): Error
-  reject(message: string, target?: string, args?: any[]): Error
-
-  notify(message: { code?: number | string; message: string; target?: string; args?: any[] }): Error
-  info(message: { code?: number | string; message: string; target?: string; args?: any[] }): Error
-  warn(message: { code?: number | string; message: string; target?: string; args?: any[] }): Error
-  error(message: { code?: number | string; message: string; target?: string; args?: any[], status?: number }): Error
-  reject(message: { code?: number | string; message: string; target?: string; args?: any[], status?: number }): Error
-}
-
-
-/**
- * Represents the user in a given context.
- * @see [capire docs](https://cap.cloud.sap/docs/node.js/authentication#cds-user)
- */
-export class User {
-  constructor(obj?: string | { id: string; attr: Record<string, string>; roles: Record<string, string> } | User)
-  id: string
-
-  /**
-   * @deprecated Use https://cap.cloud.sap/docs/node.js/events#locale instead
-   */
-  locale: string
-
-  /**
-   * @deprecated Use https://cap.cloud.sap/docs/node.js/events#tenant instead
-   */
-  tenant: string | undefined
-
-  attr: Record<string, string>
-  roles: Array<string> | Record<string, string>
-  static Privileged: typeof Privileged
-  is(role: string): boolean
-}
-
-/**
- * Subclass for executing code with superuser privileges.
- */
-declare class Privileged extends User {
-  constructor()
-  is(): boolean
-}

package/apis/internal/inference.d.ts

@@ -1,32 +0,0 @@
-// Types in this file are not part of the API.
-// They are merely meant as definitions that are used
-// in several places within the API.
-
-
-export interface Constructable<T = any> {
-	new(...args: any[]): T
-}
-
-// any class (not value) of array to represent plural types used in cds-typer.
-// Mainly used as pattern match for SingularType
-//type ArrayConstructable = Constructable<Array<unknown>>
-export interface ArrayConstructable<T = any> {
-	new(...args: any[]): T[]
-}
-
-// concrete singular type.
-// `SingularType<typeof Books>` == `Book`.
-export type SingularType<T extends ArrayConstructable<T>> = InstanceType<T>[number]
-
-// Convenient way of unwrapping the inner type from array-typed values, as well as the value type itself
-// `class MyArray<T> extends Array<T>``
-// The latter is used heavily in the CDS typer, but its behaviour depends based on how the types are imported:
-// If they are imported on a value based (`require('path/to/type')`) they will be considered `ArrayConstructable`.
-// But if they are being used on type level (JSDOC: `/* @type {import('path/to/type')} */`) they are considered an `Array` .
-// This type introduces an indirection that streamlines their behaviour for both cases.
-// For any scalar type `Unwrap` behaves idempotent.
-export type Unwrap<T> = T extends ArrayConstructable
-  ? SingularType<T>
-  : T extends Array<infer U>
-  ? U
-  : T

package/apis/linked.d.ts

@@ -1,105 +0,0 @@
-import { CSN, FQN, Association, Definition, entity, kinds } from "./csn"
-
-export type LinkedDefinition = linked & Definition & LinkedEntity & LinkedAssociation
-export type Definitions = { [name: string]: LinkedDefinition }
-// FIXME: this is only a temporary alias. Definitions is actually correct,
-// but the name may be misleading, as it is indeed a mapping of strings to LinkedDefinition objects.
-export type LinkedDefinitions = Definitions
-export interface linked {
-	is(kind: kinds | 'Association' | 'Composition'): boolean
-	name: FQN
-}
-
-interface LinkedEntity extends linked, entity {
-	constructor (properties: object)
-	keys: Definitions
-	drafts: LinkedEntity
-}
-
-interface LinkedAssociation extends linked, Association {
-	is2one: boolean
-	is2many: boolean
-}
-
-export interface LinkedCSN extends CSN {
-
-	/**
-	 * Fetches definitions matching the given filter, returning an iterator on them.
-	 * @example
-	 * ```js
-	 *   let m = cds.reflect (aParsedModel)
-	 *   for (let d of m.each('entity'))  console.log (d.kind, d.name)
-	 *   let entities = [...m.each('entity')]  //> capture all
-	 *   let entities = m.all('entity')        //> equivalent shortcut
-	 * ```
-	 */
-	each(x: Filter, defs?: Definitions): IterableIterator<any>
-
-	/**
-	 * Fetches definitions matching the given filter, returning them in an array.
-	 * Convenience shortcut for `[...reflect.each('entity')]`
-	 */
-	all(x: Filter, defs?: Definitions): any[]
-
-	/**
-	 * Fetches definitions matching the given filter, returning the first match, if any.
-	 * @example
-	 *      let service = model.find('service')
-	 * @param x - the filter
-	 * @param defs - the definitions to fetch in, default: `this.definitions`
-	 */
-	find(x: Filter, defs?: Definitions): any
-
-	/**
-	 * Calls the visitor for each definition matching the given filter.
-	 * @see [capire](https://github.wdf.sap.corp/pages/cap/node.js/api#cds-reflect-foreach)
-	 */
-	foreach(x: Filter, visitor: Visitor, defs?: Definitions): this
-	foreach(visitor: Visitor, defs?: Definitions): this
-
-	/**
-	 * Same as foreach but recursively visits each element definition
-	 * @see [capire](https://github.wdf.sap.corp/pages/cap/node.js/api#cds-reflect-foreach)
-	 */
-	forall(x: Filter, visitor: Visitor, defs?: Definitions): this
-	forall(visitor: Visitor, defs?: Definitions): this
-
-	/**
-	 * Fetches definitions declared as children of a given parent context or service.
-	 * It fetches all definitions whose fully-qualified names start with the parent's name.
-	 * Returns the found definitions as an object with the local names as keys.
-	 * @example
-	 * ```js
-	 *   let service  = model.find ('service')
-	 *   let entities = m.childrenOf (service)
-	 * ```
-	 * @param parent - either the parent itself or its fully-qualified name
-	 * @param filter - an optional filter to apply before picking a child
-	 */
-	childrenOf(parent: any | string, filter?: ((def: LinkedDefinition) => boolean)): Definitions
-
-	/**
-	 * Provides convenient access to the model's top-level definitions.
-	 * For example, you can use it in an es6-import-like fashion to avoid
-	 * working with fully-qualified names as follows:
-	 *
-	 * @example
-	 * ```js
-	 * let model = cds.reflect (cds.parse(`
-	 *     namespace our.lovely.bookshop;
-	 *     entity Books {...}
-	 *     entity Authors {...}
-	 * `))
-	 * const {Books,Authors} = model.exports
-	 * SELECT.from (Books) .where ({ID:11})
-	 * ```
-	 */
-	exports: Definitions & ((namespace: string) => Definitions)
-	entities: Definitions & ((namespace: string) => Definitions)
-	services: Definitions & ((namespace: string) => Definitions)
-	definitions: Definitions
-
-}
-
-type Visitor = (def: LinkedDefinition, name: string, parent: LinkedDefinition, defs: Definitions) => void
-type Filter = string | ((def: LinkedDefinition) => boolean)