@cap-js/cds-types 0.0.1 → 0.2.0

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,71 +9,112 @@ 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});
-  http?: {req: express.Request, res: express.Response}
+
+  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 | {})[]
+
+  params: (string | object)[]
+
   method: string
+
   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
+
   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
+  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)
+
+  constructor (obj?: string | { id: string, attr: Record<string, string>, roles: Array<string> | Record<string, string> } | User)
   id: string
 
   /**
@@ -112,15 +128,22 @@ export class User {
   tenant: string | undefined
 
   attr: Record<string, string>
+
   roles: Array<string> | Record<string, string>
+
   static Privileged: typeof Privileged
-  is(role: string): boolean
+
+  is (role: string): boolean
+
 }
 
 /**
  * Subclass for executing code with superuser privileges.
  */
 declare class Privileged extends User {
-  constructor()
-  is(): boolean
+
+  constructor ()
+
+  is (): boolean
+
 }

package/apis/internal/inference.d.ts

@@ -4,14 +4,14 @@
 
 
 export interface Constructable<T = any> {
-	new(...args: any[]): T
+  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>>
+// type ArrayConstructable = Constructable<Array<any>>
 export interface ArrayConstructable<T = any> {
-	new(...args: any[]): T[]
+  new(...args: any[]): T[]
 }
 
 // concrete singular type.
@@ -28,5 +28,39 @@ export type SingularType<T extends ArrayConstructable<T>> = InstanceType<T>[numb
 export type Unwrap<T> = T extends ArrayConstructable
   ? SingularType<T>
   : T extends Array<infer U>
-  ? U
-  : T
+    ? 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>>>

package/apis/linked.d.ts

@@ -1,83 +1,89 @@
-import { CSN, FQN, Association, Definition, entity, kinds } from "./csn"
+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
+  is(kind: kinds | 'Association' | 'Composition'): boolean
+  name: FQN
 }
 
 interface LinkedEntity extends linked, entity {
-	constructor (properties: object)
-	keys: Definitions
-	drafts: LinkedEntity
+  keys: Definitions
+  drafts?: LinkedEntity
 }
 
 interface LinkedAssociation extends linked, Association {
-	is2one: boolean
-	is2many: boolean
+  is2one: boolean
+  is2many: boolean
 }
 
 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>
+  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[]
+  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 {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
+  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
+  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
+  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
-	 *      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
+  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 {...}
@@ -85,11 +91,12 @@ 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)
-	services: Definitions & ((namespace: string) => Definitions)
-	definitions: Definitions
+  exports: Definitions & ((namespace: string) => Definitions)
+  entities: Definitions & ((namespace: string) => Definitions)
+  services: Definitions & ((namespace: string) => Definitions)
+  definitions: Definitions
 
 }
 

package/apis/log.d.ts

@@ -1,133 +1,136 @@
-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 = {
 
-    /**
+  /**
      * Returns a trace logger for the given module if trace is switched on for it,
      * otherwise returns null. All cds runtime packages use this method for their
      * trace and debug output.
      *
      * 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)
      */
-    (name: string, options?: string | number | { level?: number, label?: string, prefix?: string }): Logger
+  (name: string, options?: string | number | { level?: number, label?: string, prefix?: string }): Logger,
 
-    /**
+  /**
      * 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
-    
-    /**
+  format: Formatter,
+
+  /**
      * Set a custom logger.
-     * ```
+     * ```js
      *   cds.log.Logger = ...
      * ```
      */
-    Logger: Logger
+  Logger: Logger,
 
-    winstonLogger (LoggerOptions?: {level?: string, levels?: any, format?: any, transports?: any, exitOnError?: boolean | Function, silent?: boolean})
+  // FIXME
+  /* eslint-disable-next-line @typescript-eslint/ban-types */
+  winstonLogger (LoggerOptions?: { level?: string, levels?: any, format?: any, transports?: any, exitOnError?: boolean | Function, silent?: boolean }),
 }
 
 declare class Logger {
-    /**
-     * Logs with 'trace' level
-     */
-    trace: Log
 
-    /**
+
+  /**
+    * Logs with 'trace' level
+    */
+  trace: Log
+
+  /**
      * Logs with 'debug' level
      */
-    debug: Log
+  debug: Log
 
-    /**
+  /**
      * Logs with 'info' level
      */
-    info: Log
+  info: Log
 
-    /**
+  /**
      * Logs with 'warn' level
      */
-    warn: Log
+  warn: Log
 
-    /**
+  /**
      * Logs with 'error' level
      */
-    error: Log
+  error: Log
 
-    /**
+  /**
      * Logs with default level
      */
-    log: Log
+  log: Log
 
-    /**
+  /**
      * @returns whether 'trace' level is active
      */
-    _trace: boolean
+  _trace: boolean
 
-    /**
+  /**
      * @returns whether 'debug' level is active
      */
-     _debug: boolean
+  _debug: boolean
 
-    /**
+  /**
      * @returns whether 'info' level is active
      */
-     _info: boolean
+  _info: boolean
 
-    /**
+  /**
      * @returns whether 'warn' level is active
      */
-     _warn: boolean
+  _warn: boolean
 
-    /**
+  /**
      * @returns whether 'error' level is active
      */
-     _error: boolean
+  _error: boolean
 
-    /**
+  /**
      * Change the format for this logger instance:
      * ```
      *   cds.log('foo').setFormat((module, level, ...args) => [ '[', module, ']', ...args ])
@@ -135,31 +138,36 @@ declare class Logger {
      *
      * The formatter shall return an array of arguments, which are passed to the logger (for example, `console.log()`)
      */
-     setFormat(formatter: Formatter)
+  setFormat (formatter: Formatter)
+
 }
 
 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[]
+  (module: string, level: number, args: any[]): any[],
 }
 
 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
+  (message?: any, ...optionalParams: any[]): void,
 }
 
 declare enum levels {
-    SILENT = 0, ERROR = 1, WARN = 2, INFO = 3, DEBUG = 4, TRACE = 5, SILLY = 5, VERBOSE = 5
+  // FIXME: check if this is a copy-paste error
+  /* eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values */
+  SILENT = 0, ERROR = 1, WARN = 2, INFO = 3, DEBUG = 4, TRACE = 5, SILLY = 5, VERBOSE = 5
 }