@cap-js/cds-types 0.1.0 → 0.2.0

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,4 +1,4 @@
-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 }
@@ -6,24 +6,23 @@ export type Definitions = { [name: string]: LinkedDefinition }
 // 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
 	 * ```js
@@ -33,38 +32,38 @@ export interface LinkedCSN extends CSN {
 	 *   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 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.
@@ -76,9 +75,9 @@ export interface LinkedCSN extends CSN {
 	 * @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:
@@ -94,10 +93,10 @@ export interface LinkedCSN extends CSN {
 	 * 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

@@ -16,11 +16,11 @@ export declare const log: LogFactory
  *
  * @param name - logger name
  */
-export declare function debug(name: string): undefined | Log
+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.
@@ -47,9 +47,9 @@ declare type LogFactory = {
      * @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 ]
@@ -57,76 +57,80 @@ declare type LogFactory = {
      *
      * 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 ])
@@ -134,11 +138,13 @@ 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
@@ -146,19 +152,22 @@ declare type Formatter = {
      * @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, ...)`
      */
-     (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
 }

package/apis/models.d.ts

@@ -1,21 +1,20 @@
-import { Query as CQN, expr, _xpr } from "./cqn"
-import { LinkedCSN } from "./linked"
-import { CSN } from "./csn"
-import * as cds from './cds'
+import { Query as CQN, expr, _xpr } from './cqn'
+import { LinkedCSN } from './linked'
+import { CSN } from './csn'
 
 type _flavor = 'parsed' | 'xtended' | 'inferred'
 type _odata_options = {
-    flavor?: 'v2' | 'v4' | 'w4'| 'x4',
-    version?: 'v2' | 'v4',
-    structs?: boolean,
-    refs?: boolean,
+  flavor?: 'v2' | 'v4' | 'w4' | 'x4',
+  version?: 'v2' | 'v4',
+  structs?: boolean,
+  refs?: boolean,
 }
 type _options = {
-    flavor?: _flavor,
-    plain?: boolean,
-    docs?: boolean,
-    names?: string,
-    odata?: _odata_options,
+  flavor?: _flavor,
+  plain?: boolean,
+  docs?: boolean,
+  names?: string,
+  odata?: _odata_options,
 } | _flavor
 
 type JSON = string
@@ -23,7 +22,7 @@ type YAML = string
 type CDL = string
 type SQL = string
 type XML = string
-type EDM = { $version:string }
+type EDM = { $version: string }
 type EDMX = XML
 type filename = string
 
@@ -31,21 +30,23 @@ type filename = string
 /**
  * The effective CDS model loaded during bootstrapping, which contains all service and entity definitions,
  * including required services.
+ * Should only be ever set explictly in test scenarios!
  */
-export const model : LinkedCSN | undefined  // was ?: LinkedCSN
+export let model: LinkedCSN | undefined
 
 /**
  * Provides a set of methods to parse a given model, query or expression.
  * You can also use `cds.parse()` as a shortcut to `cds.parse.cdl()`.
  */
-export const parse : {
-    /** Shortcut to `cds.parse.cdl()` */
-    (cdl:CDL) : CSN
-    cdl (cdl:CDL) : CSN
-    cql (src:string) : CQN
-    expr (src:string) : expr
-    xpr (src:string) : _xpr
-    ref (src:string) : string[]
+export const parse: {
+
+  /** Shortcut to `cds.parse.cdl()` */
+  (cdl: CDL): CSN,
+  cdl (cdl: CDL): CSN,
+  cql (src: string): CQN,
+  expr (src: string): expr,
+  xpr (src: string): _xpr,
+  ref (src: string): string[],
 }
 
 /**
@@ -54,13 +55,13 @@ export const parse : {
  * Essentially a shortcut for `cds.compile.to.csn(files)`
  * @param files - filenames of models or if folder containing models
  */
-export function get (files: '*' | filename | filename[], o?:_options): Promise<CSN>
+export function get (files: '*' | filename | filename[], o?: _options): Promise<CSN>
 
 /**
  * Shortcut for `cds.get(files, 'inferred')`
  * @param files - filenames of models or if folder containing models
  */
-export function load (files: '*' | filename | filename[], o?:_options): Promise<CSN>
+export function load (files: '*' | filename | filename[], o?: _options): Promise<CSN>
 
 
 /**
@@ -90,82 +91,83 @@ export const reflect: (model: CSN) => LinkedCSN
 * You can also use `cds.compile(csn).to('<output>')` as a fluent variant.
 */
 export const compile: {
-   /** Shortcut for `cds.compile.to.csn()` */
-   cdl (model:CDL, o?:_options) : CSN,
-
-   for: {
-       odata (model:CSN, o?:_options) : CSN
-       sql (model:CSN, o?:_options) : CSN
-   },
-   to: {
-       parsed:{
-           csn (files:filename[], o?:_options) : Promise<CSN>
-           csn (model:CDL, o?:_options) : CSN
-       }
-       xtended:{
-           csn (files:filename[], o?:_options) : Promise<CSN>
-           csn (model:CDL, o?:_options) : CSN
-       }
-       inferred:{
-           csn (files:filename[], o?:_options) : Promise<CSN>
-           csn (model:CDL, o?:_options) : CSN
-       }
-       csn (files:filename[], o?:_options) : Promise<CSN>
-       csn (model:CDL, o?:_options) : CSN
-       yml (model:CSN, o?:_options) : YAML
-       yaml (model:CSN, o?:_options) : YAML
-       json (model:CSN, o?:_options) : JSON
-       sql (model:CSN, o?:_options) : SQL[]
-       cdl (model:CSN, o?:_options) : CDL | Iterable<[CDL,{file:filename}]>
-       edm (model:CSN, o?:_options|_odata_options) : EDM | string
-       edmx (model:CSN, o?:_options|_odata_options) : EDMX | Iterable<[EDMX,{file:filename}]>
-       hdbcds (model:CSN, o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
-       hdbtable (model:CSN, o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
-   }
-
-   /** Fluent API variant */
-   (model: CSN | CDL) : {
-       for: {
-           odata (o?:_options) : CSN
-           sql (o?:_options) : CSN
-       },
-       to: {
-           parsed:{ csn (o?:_options) : CSN }
-           xtended:{ csn (o?:_options) : CSN }
-           inferred:{ csn (o?:_options) : CSN }
-           csn (o?:_options) : CSN
-           yml (o?:_options) : YAML
-           yaml (o?:_options) : YAML
-           json (o?:_options) : JSON
-           sql (o?:_options) : SQL[]
-           cdl (o?:_options) : CDL | Iterable<[CDL,{file:filename}]>
-           edm (o?:_options|_odata_options) : EDM | string
-           edmx (o?:_options|_odata_options) : EDMX | Iterable<[EDMX,{file:filename}]>
-           hdbcds (o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
-           hdbtable (o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
-       }
-   }
-
-   /** Async fluent variant reading from files */
-   (files: filename[]) : {
-       for: {
-           odata (o?:_options) : Promise<CSN>
-           sql (o?:_options) : Promise<CSN>
-       },
-       to: {
-           parsed:{ csn (o?:_options) : Promise <CSN> }
-           xtended:{ csn (o?:_options) : Promise <CSN> }
-           inferred:{ csn (o?:_options) : Promise <CSN> }
-           csn (o?:_options) : Promise <CSN>
-           yml (o?:_options) : Promise <YAML>
-           yaml (o?:_options) : Promise <YAML>
-           json (o?:_options) : Promise <JSON>
-           sql (o?:_options) : Promise <SQL[]>
-           cdl (o?:_options) : Promise <CDL | Iterable<[CDL,{file:filename}]>>
-           edm (o?:_options|_odata_options) : Promise <EDM | string>
-           edmx (o?:_options|_odata_options) : Promise <EDMX | Iterable<[EDMX,{file:filename}]>>
-           hdbcds (o?:_options) : Promise <SQL | Iterable<[SQL,{file:filename}]>>
-           hdbtable (o?:_options) : Promise <SQL | Iterable<[SQL,{file:filename}]>>
-       }
-   }
+
+  /** Shortcut for `cds.compile.to.csn()` */
+  cdl (model: CDL, o?: _options): CSN,
+
+  for: {
+    odata (model: CSN, o?: _options): CSN,
+    sql (model: CSN, o?: _options): CSN,
+  },
+  to: {
+    parsed: {
+      csn (files: filename[], o?: _options): Promise<CSN>,
+      csn (model: CDL, o?: _options): CSN,
+    },
+    xtended: {
+      csn (files: filename[], o?: _options): Promise<CSN>,
+      csn (model: CDL, o?: _options): CSN,
+    },
+    inferred: {
+      csn (files: filename[], o?: _options): Promise<CSN>,
+      csn (model: CDL, o?: _options): CSN,
+    },
+    csn (files: filename[], o?: _options): Promise<CSN>,
+    csn (model: CDL, o?: _options): CSN,
+    yml (model: CSN, o?: _options): YAML,
+    yaml (model: CSN, o?: _options): YAML,
+    json (model: CSN, o?: _options): JSON,
+    sql (model: CSN, o?: _options): SQL[],
+    cdl (model: CSN, o?: _options): CDL | Iterable<[CDL, { file: filename }]>,
+    edm (model: CSN, o?: _options | _odata_options): EDM | string,
+    edmx (model: CSN, o?: _options | _odata_options): EDMX | Iterable<[EDMX, { file: filename }]>,
+    hdbcds (model: CSN, o?: _options): SQL | Iterable<[SQL, { file: filename }]>,
+    hdbtable (model: CSN, o?: _options): SQL | Iterable<[SQL, { file: filename }]>,
+  },
+
+  /** Fluent API variant */
+  (model: CSN | CDL): {
+    for: {
+      odata (o?: _options): CSN,
+      sql (o?: _options): CSN,
+    },
+    to: {
+      parsed: { csn (o?: _options): CSN },
+      xtended: { csn (o?: _options): CSN },
+      inferred: { csn (o?: _options): CSN },
+      csn (o?: _options): CSN,
+      yml (o?: _options): YAML,
+      yaml (o?: _options): YAML,
+      json (o?: _options): JSON,
+      sql (o?: _options): SQL[],
+      cdl (o?: _options): CDL | Iterable<[CDL, { file: filename }]>,
+      edm (o?: _options | _odata_options): EDM | string,
+      edmx (o?: _options | _odata_options): EDMX | Iterable<[EDMX, { file: filename }]>,
+      hdbcds (o?: _options): SQL | Iterable<[SQL, { file: filename }]>,
+      hdbtable (o?: _options): SQL | Iterable<[SQL, { file: filename }]>,
+    },
+  },
+
+  /** Async fluent variant reading from files */
+  (files: filename[]): {
+    for: {
+      odata (o?: _options): Promise<CSN>,
+      sql (o?: _options): Promise<CSN>,
+    },
+    to: {
+      parsed: { csn (o?: _options): Promise <CSN> },
+      xtended: { csn (o?: _options): Promise <CSN> },
+      inferred: { csn (o?: _options): Promise <CSN> },
+      csn (o?: _options): Promise <CSN>,
+      yml (o?: _options): Promise <YAML>,
+      yaml (o?: _options): Promise <YAML>,
+      json (o?: _options): Promise <JSON>,
+      sql (o?: _options): Promise <SQL[]>,
+      cdl (o?: _options): Promise <CDL | Iterable<[CDL, { file: filename }]>>,
+      edm (o?: _options | _odata_options): Promise <EDM | string>,
+      edmx (o?: _options | _odata_options): Promise <EDMX | Iterable<[EDMX, { file: filename }]>>,
+      hdbcds (o?: _options): Promise <SQL | Iterable<[SQL, { file: filename }]>>,
+      hdbtable (o?: _options): Promise <SQL | Iterable<[SQL, { file: filename }]>>,
+    },
+  },
 }