@cap-js/cds-types 0.0.1 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # cds-types
 
-<!-- [![REUSE status](https://api.reuse.software/badge/github.com/cap-js/cds-types)](https://api.reuse.software/info/github.com/cap-js/cds-types)
-![Unit Tests passing](https://github.com/cap-js/cds-types/actions/workflows/test.yml/badge.svg) -->
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/cds-types)](https://api.reuse.software/info/github.com/cap-js/cds-types)
+![Unit Tests passing](https://github.com/cap-js/cds-types/actions/workflows/test.yml/badge.svg)
 
 ## About this project
 
@@ -15,8 +15,19 @@ Find more information on the APIs in the [Node.js SDK documentation](https://cap
 
 ## Support, Feedback, Contributing
 
+### Local Setup
+
+After cloning, just run
+
+```sh
+npm run setup
+```
+
+which installs all dependencies.
+
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/cds-types/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](CONTRIBUTING.md).
 
+
 ## Security / Disclosure
 
 If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/.github/blob/main/SECURITY.md) on how to report it. Please do not create GitHub issues for security-related doubts or problems.

package/apis/cds.d.ts

@@ -1,33 +1,37 @@
-import * as ql from './ql'
+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'
 
-declare global {
-	const cds : cds_facade
-}
+// 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'
 
-export = cds
+// 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?
 
-type cds_facade = {}
-& import('./core').default
-& import('./env').default
-& import('./models').default
-& import('./server').default
-& import('./services').QueryAPI
-& import('./services').default
-& import('./events').default
-& import('./ql').cds_ql
-& import('./log')
-& import('./utils')
-& import('./test')
+// 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: typeof cds.ql.SELECT
-	const INSERT: typeof cds.ql.INSERT
-	const UPSERT: typeof cds.ql.UPSERT
-	const UPDATE: typeof cds.ql.UPDATE
-	const DELETE: typeof cds.ql.DELETE
-	const CREATE: typeof cds.ql.CREATE
-	const DROP: typeof cds.ql.DROP
+  // 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>
@@ -36,5 +40,5 @@ declare global {
 	type UPDATE<T> = ql.UPDATE<T>
 	type DELETE<T> = ql.DELETE<T>
 	type CREATE<T> = ql.CREATE<T>
-	type DROP<T>   = ql.DROP<T>
+	type DROP<T> = ql.DROP<T>
 }

package/apis/core.d.ts

@@ -2,100 +2,107 @@ import { LinkedAssociation, LinkedEntity, linked } from './linked'
 import * as csn from './csn'
 import { service } from './server'
 
-// These are classes actually -> using the new() => interface trick
-export type Association = new(_?:object) => LinkedAssociation
-export type Composition = new(_?:object) => LinkedAssociation
-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
+type Intersect<T extends readonly unknown[]> = T extends [infer Head, ...infer Tail]
+  ? Head & Intersect<Tail>
+  : unknown
 
-export default class cds {
-  // infer (query : cqn, model : csn) : LinkedDefinition
+/**
+ * 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) }
 
-  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: {}
-  }
+/**
+ * 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 Associations from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
-   */
-  Association: Association
+/**
+ * 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) }
 
-  /**
-   * Base class for linked Compositions from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
-   */
-  Composition: Composition
+export interface event extends linked, csn.struct {}
+export class event { constructor (_?: object) }
 
-  /**
-   * Base class for linked entities from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-entity)
-   */
-  entity: entity
+export interface type extends linked, csn.type {}
+export class type { constructor (_?: object) }
 
-  event: event
-  type: type
-  array: array
-  struct: struct
+export interface array extends linked, csn.type {}
+export class array { constructor (_?: object) }
 
-  /**
-   * Add aspects to a given object, for example:
-   *
-   *    extend (Object.prototype) .with (class {
-   *       get foo() { return ... }
-   *       bar() {...}
-   *    }.prototype)
-   */
-  extend<T>(target: T): {
-    with<E extends readonly unknown[]>(...ext: E): T & Intersect<E>
-  }
+export interface struct extends linked, csn.struct {}
+export class struct { constructor (_?: object) }
 
-  /**
-   * Equip a given facade object with getters for lazy-loading modules instead
-   * of static requires. Example:
-   *
-   *    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.
-   */
-  lazify <T>(target: T) : T
+// infer (query : cqn, model : csn) : LinkedDefinition
+export const builtin: {
 
   /**
-   * Prepare a node module for lazy-loading submodules instead
-   * of static requires. Example:
-   *
-   *    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.
+   * Base classes of linked definitions from reflected models.
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-builtin-classes)
    */
-  lazified <T>(target: T) : T
+  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>,
 }
 
-type Intersect<T extends readonly unknown[]> = T extends [infer Head, ...infer Tail]
-  ? Head & Intersect<Tail>
-  : unknown
+/**
+ * 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,76 +1,98 @@
-import { entity } from "./csn" // cyclic dependency
+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
-}}
+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
-type data = Record<string,any>
+
+/** @private */
+type data = Record<string, any>
+
+/** @private */
 type name = string
-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
-type ordering_term = expr & { sort?: "asc"|"desc", nulls?: "first"|"last" }
+
+/** @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
-type ref = {ref:( name & { id?:string, where?:expr, args?:expr[] } )[]}
-type val = {val:any}
-type xpr = {xpr:_xpr}
-type _xpr = ( expr | operator ) []
+
+/** @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
-type function_call = {func: string, args: {[key: string]: unknown}[]}
 
-export type enum_literal = {"#": string}
-export type expr_literal = {"=": 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

@@ -4,6 +4,7 @@ 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
@@ -46,19 +47,21 @@ export type Definition = context & service & type & struct & entity & Associatio
 // NOTE: If we use & instead of | CSN.definitions values would be reduced to <never>
 
 /**
- * Extensions capture extend Foo with { ... } directives.
+ * Extensions capture `extend Foo with { ... }` directives.
  */
 export type Extension = {
-  extend: FQN
-  elements?: { [name: string]: Element }
-  includes?: FQN[]
+  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 any_ {
+  kind?: kinds
+}
 export interface context extends any_ { }
 export interface service extends any_ { }
 
@@ -68,6 +71,7 @@ export interface type extends any_ {
 }
 
 export interface struct extends type {
+
   /**
    * References to definitions to be included.
    * Not available after extensions have been applied.
@@ -76,40 +80,45 @@ export interface struct extends type {
   elements: { [name: string]: Element }
 }
 
-export interface entity extends Omit<struct,'elements'> {
+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
+  elements: EntityElements
   // REVISIT: following should move to LinkedCSN
   keys: { [name: string]: Definition }
-  drafts: entity
+  drafts?: entity
 }
 
 export type EntityElements = {
-    [name:string]: Element & {
-        key? : boolean
-        virtual? : boolean
-        unique? : boolean
-        notNull? : boolean
-    }
+  [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:'*'}
+   * The specified cardinality. to-one = `{max:1}`, to-many = `{max:'*'}`
    */
-  cardinality?: { src?: 1; min?: 1 | 0; max?: 1 | '*' }
+  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
    */

package/apis/env.d.ts

@@ -1,25 +1,22 @@
-export default class {
-  /**
-   * 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.
-   */
-  env : {
-    build: any,
-    hana: any,
-    i18n: any,
-    mtx: any,
-    requires: any,
-    folders: any,
-    odata: any,
-    query: any,
-    sql: any
-  }
+/**
+ * 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
 
-  requires: any
-  version: string
-  home: string
-  root: string
-
-}
+export const requires: any
+export const version: string
+export const home: string
+export const root: string