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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-types",
-  "version": "0.2.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,36 +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",
-    "lint": "eslint . --ext .ts",
-    "lint:fix": "eslint . --ext .ts --fix",
-    "setup": "npm i && npm i file:. --no-save --force"
+    "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.5.0",
-    "@stylistic/eslint-plugin": "^1.5.3",
+    "@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",
-    "@typescript-eslint/eslint-plugin": "^6.18.1",
-    "@typescript-eslint/parser": "^6.18.1",
     "axios": "^1.6.2",
     "chai": "^4.3.10",
-    "eslint": "^8.56.0",
+    "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,108 +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
-
-/**
- * Base class for linked Associations from reflected models.
- * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
- */
-export interface Association extends LinkedAssociation {}
-export declare class Association { constructor (_?: object) }
-
-/**
- * Base class for linked Compositions from reflected models.
- * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-composition)
- */
-export interface Composition extends Association {}
-export declare class Composition { constructor (_?: object) }
-
-/**
- * Base class for linked entities from reflected models.
- * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-entity)
- */
-export interface entity extends LinkedEntity {}
-export declare class entity { constructor (_?: object) }
-
-export interface event extends linked, csn.struct {}
-export class event { constructor (_?: object) }
-
-export interface type extends linked, csn.type {}
-export class type { constructor (_?: object) }
-
-export interface array extends linked, csn.type {}
-export class array { constructor (_?: object) }
-
-export interface struct extends linked, csn.struct {}
-export class struct { constructor (_?: object) }
-
-// 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: typeof Association,
-    Composition: typeof Composition,
-    entity: typeof entity,
-    event: typeof event,
-    type: typeof type,
-    array: typeof array,
-    struct: typeof struct,
-    service: service,
-  },
-  types: Record<string, object>,
-}
-
-/**
- * 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 any[]>(...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,98 +0,0 @@
-import { entity } from './csn' // cyclic dependency
-import { UnionToIntersection, UnionsToIntersections } from './internal/inference'
-
-// 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 = UnionToIntersection<ref | SELECT> & { as?: name, join?: name, on?: xpr }
-export type column_expr = UnionToIntersection<expr> & { as?: name, cast?: any, expand?: column_expr[], inline?: column_expr[] }
-export type predicate = UnionsToIntersections<_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]: any }[] }
-
-export type enum_literal = { '#': string }
-export type expr_literal = { '=': string }

package/apis/csn.d.ts

@@ -1,126 +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,149 +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 | object)[]
-
-  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: Array<string> | 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,66 +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<any>>
-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
-
-
-/*
- * the following three types are used to convert union types to intersection types.
- * We need these as our types currently lack generics in places where we would need them to clearly decide
- * on a subtype in the case of a union type. This leads to the following problem:
- *
- * ```ts
- * type A = { a: number }
- * type B = { b: string }
- * type Foo = A | B
- * function f(): Foo { ... }
- * const x = f()
- * x.a  // error, could also be B
- * ```
- *
- * While we should have:
- *
- * ```ts
- * function f<T extends Foo>(): T { ... }
- * const x = f<A>()
- * x.a
- * ```ts
- *
- * Since we don't do that yet, we opt for intersection types instead.
- * By also wrapping it in Partial, we at least force the user to check for the presence of any
- * attribute they try to access.
- *
- * Places where these types are used are subject to a rework!
- * the idea behind the conversion can be found in this excellent writeup: https://fettblog.eu/typescript-union-to-intersection/
- */
-export type Scalarise<A> = A extends Array<infer N> ? N : A
-export type UnionToIntersection<U> = Partial<(U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never>
-export type UnionsToIntersections<U> = Array<UnionToIntersection<Scalarise<U>>>