@cap-js/cds-types 0.0.1 → 0.1.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
 

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
+	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>
@@ -37,4 +41,4 @@ declare global {
 	type DELETE<T> = ql.DELETE<T>
 	type CREATE<T> = ql.CREATE<T>
 	type DROP<T>   = ql.DROP<T>
-}
+}

package/apis/core.d.ts

@@ -2,100 +2,94 @@ 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
 
-export default class cds {
-  // infer (query : cqn, model : csn) : LinkedDefinition
-
-  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 Associations from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
-   */
-  Association: Association
-
-  /**
-   * Base class for linked Compositions from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
-   */
-  Composition: Composition
-
-  /**
-   * Base class for linked entities from reflected models.
-   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-entity)
-   */
-  entity: entity
-
-  event: event
-  type: type
-  array: array
-  struct: struct
-
+// infer (query : cqn, model : csn) : LinkedDefinition
+export const builtin: {
   /**
-   * Add aspects to a given object, for example:
-   *
-   *    extend (Object.prototype) .with (class {
-   *       get foo() { return ... }
-   *       bar() {...}
-   *    }.prototype)
+   * Base classes of linked definitions from reflected models.
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-builtin-classes)
    */
-  extend<T>(target: T): {
-    with<E extends readonly unknown[]>(...ext: E): T & Intersect<E>
+  classes: {
+    Association: Association
+    Composition: Composition
+    entity: entity
+    event: event
+    type: type
+    array: array
+    struct: struct
+    service: service
   }
+  types: {}
+}
 
-  /**
-   * 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
-
-  /**
-   * 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.
-   */
-  lazified <T>(target: T) : T
-
+/**
+ * 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>
 }
 
-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

@@ -56,20 +56,31 @@ export type DROP = {DROP:{
 	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}

package/apis/csn.d.ts

@@ -46,7 +46,7 @@ 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
@@ -103,7 +103,7 @@ 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 | '*' }
   /**

package/apis/env.d.ts

@@ -1,11 +1,10 @@
-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 : {
+/**
+ * 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,
@@ -15,11 +14,9 @@ export default class {
     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

package/apis/events.d.ts

@@ -1,32 +1,7 @@
 import { LinkedDefinition } from './linked'
 import { Query } from './cqn'
 import { ref } from './cqn'
-import * as express from "express"
-
-
-export default class cds {
-
-  /**
-   * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
-   */
-  EventContext: typeof EventContext
-
-  /**
-   * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
-   */
-  Event: typeof Event
-
-  /**
-   * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
-   */
-  Request: typeof Request
-
-  /**
-   * Represents the user in a given context.
-   * @see [capire docs](https://cap.cloud.sap/docs/node.js/authentication#cds-user)
-   */
-  User: typeof User
-}
+import * as express from 'express'
 
 
 /**
@@ -34,7 +9,7 @@ export default class cds {
  * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
  */
 export class EventContext {
-  constructor(properties:{event:string, data?:object, query?:object, headers:object});
+  constructor(properties:{event:string, data?:object, query?:object, headers?:object});
   http?: {req: express.Request, res: express.Response}
   tenant: string
   user: User
@@ -62,7 +37,7 @@ export class Request extends Event {
   path: string
   target: LinkedDefinition
   /**
-   * Shortcut to {@link target.name}
+   * Shortcut to {@link Request.target | target (entity) name}
    * @see https://cap.cloud.sap/docs/node.js/events#req-entity
    */
   entity: string
@@ -97,6 +72,10 @@ export class Request extends Event {
 }
 
 
+/**
+ * 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

package/apis/linked.d.ts

@@ -2,7 +2,9 @@ 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
@@ -24,10 +26,12 @@ export interface LinkedCSN extends CSN {
 	/**
 	 * Fetches definitions matching the given filter, returning an iterator on them.
 	 * @example
-	 * 		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
+	 * ```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>
 
@@ -41,8 +45,8 @@ export interface LinkedCSN extends CSN {
 	 * Fetches definitions matching the given filter, returning the first match, if any.
 	 * @example
 	 *      let service = model.find('service')
-	 * @param {Filter} [x]  the filter
-	 * @param {Definitions} [defs]  the definitions to fetch in, default: `this.definitions`
+	 * @param x - the filter
+	 * @param defs - the definitions to fetch in, default: `this.definitions`
 	 */
 	find(x: Filter, defs?: Definitions): any
 
@@ -65,10 +69,12 @@ export interface LinkedCSN extends CSN {
 	 * 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
-	 *      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
+	 * ```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
 
@@ -78,6 +84,7 @@ export interface LinkedCSN extends CSN {
 	 * working with fully-qualified names as follows:
 	 *
 	 * @example
+	 * ```js
 	 * let model = cds.reflect (cds.parse(`
 	 *     namespace our.lovely.bookshop;
 	 *     entity Books {...}
@@ -85,6 +92,7 @@ export interface LinkedCSN extends CSN {
 	 * `))
 	 * const {Books,Authors} = model.exports
 	 * SELECT.from (Books) .where ({ID:11})
+	 * ```
 	 */
 	exports: Definitions & ((namespace: string) => Definitions)
 	entities: Definitions & ((namespace: string) => Definitions)

package/apis/log.d.ts

@@ -1,23 +1,22 @@
-export = cds
-declare class cds {
-    /**
-     * Create a new logger, or install a custom log formatter
-     */
-    log: LogFactory
 
-    /**
-     * Shortcut to `cds.log(...).debug`, returning `undefined` if `cds.log(...)._debug` is `false`.
-     * Use like this:
-     * ```
-     *   const dbg = cds.debug('foo')
-     *   ...
-     *   dbg && dbg('message')
-     * ```
-     *
-     * @param name logger name
-     */
-    debug(name: string): undefined | Log
-}
+/**
+ * Create a new logger, or install a custom log formatter
+ */
+export declare const log: LogFactory
+
+/**
+ * Shortcut to `cds.log(...).debug`, returning `undefined` if `cds.log(...)._debug` is `false`.
+ * Use like this:
+ * @example
+ * ```js
+ *   const dbg = cds.debug('foo')
+ *   ...
+ *   dbg && dbg('message')
+ * ```
+ *
+ * @param name - logger name
+ */
+export declare function debug(name: string): undefined | Log
 
 declare type LogFactory = {
 
@@ -28,23 +27,23 @@ declare type LogFactory = {
      *
      * By default this logger would prefix all output with `[sql] - `
      * You can change this by specifying another prefix in the options:
-     *
-     * ```
+     * @example
+     * ```js
      *   const LOG = cds.log('sql|db', { prefix: 'cds.ql' })
      * ```
      *
      * Call `cds.log()` for a given module again to dynamically change the log level
      * of all formerly created loggers, for example:
-     *
-     * ```
+     * @example
+     * ```js
      *   const LOG = cds.log('sql')
      *   LOG.info ('this will show, as default level is info')
      *   cds.log('sql', 'warn')
      *   LOG.info('this will be suppressed now')
      * ```
      *
-     * @param name logger name
-     * @param options level, label and prefix
+     * @param name - logger name
+     * @param options - level, label and prefix
      * @returns the logger
      * @see [capire](https://cap.cloud.sap/docs/node.js/cds-log)
      */
@@ -52,17 +51,17 @@ declare type LogFactory = {
 
     /**
      * Set a custom formatter function like that:
-     * ```
+     * ```js
      *   cds.log.format = (module, level, ...args) => [ '[', module, ']', ...args ]
      * ```
      *
      * The formatter shall return an array of arguments, which are passed to the logger (for example, `console.log()`)
      */
     format: Formatter
-    
+
     /**
      * Set a custom logger.
-     * ```
+     * ```js
      *   cds.log.Logger = ...
      * ```
      */
@@ -142,9 +141,9 @@ declare type Formatter = {
     /**
      * Custom format function
      *
-     * @param module logger name
-     * @param level log level
-     * @param args additional arguments
+     * @param module - logger name
+     * @param level - log level
+     * @param args - additional arguments
      * @returns an array of arguments, which are passed to the logger (for example, `console.log()`)
      */
     (module: string, level: number, args: any[]): any[]
@@ -154,8 +153,8 @@ declare type Log = {
     /**
      * Logs a message
      *
-     * @param message text to log
-     * @param optionalParams additional parameters, same as in `console.log(text, param1, ...)`
+     * @param message - text to log
+     * @param optionalParams - additional parameters, same as in `console.log(text, param1, ...)`
      */
      (message?: any, ...optionalParams: any[]): void
 }