@cap-js/cds-types 0.0.1

package/apis/events.d.ts

@@ -0,0 +1,126 @@
+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
+}
+
+
+/**
+ * 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 | {})[]
+  method: string
+  path: string
+  target: LinkedDefinition
+  /**
+   * Shortcut to {@link target.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
+}
+
+
+export class User {
+  constructor(obj?: string | { id: string; attr: Record<string, string>; roles: 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

@@ -0,0 +1,32 @@
+// 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<unknown>>
+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

package/apis/linked.d.ts

@@ -0,0 +1,97 @@
+import { CSN, FQN, Association, Definition, entity, kinds } from "./csn"
+
+export type LinkedDefinition = linked & Definition & LinkedEntity & LinkedAssociation
+export type Definitions = { [name: string]: LinkedDefinition }
+
+export interface linked {
+	is(kind: kinds | 'Association' | 'Composition'): boolean
+	name: FQN
+}
+
+interface LinkedEntity extends linked, entity {
+	constructor (properties: object)
+	keys: Definitions
+	drafts: LinkedEntity
+}
+
+interface LinkedAssociation extends linked, Association {
+	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
+	 */
+	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[]
+
+	/**
+	 * 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`
+	 */
+	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
+
+	/**
+	 * 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
+
+	/**
+	 * 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
+	 */
+	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
+	 * let model = cds.reflect (cds.parse(`
+	 *     namespace our.lovely.bookshop;
+	 *     entity Books {...}
+	 *     entity Authors {...}
+	 * `))
+	 * 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
+
+}
+
+type Visitor = (def: LinkedDefinition, name: string, parent: LinkedDefinition, defs: Definitions) => void
+type Filter = string | ((def: LinkedDefinition) => boolean)

package/apis/log.d.ts

@@ -0,0 +1,165 @@
+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
+}
+
+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:
+     *
+     * ```
+     *   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:
+     *
+     * ```
+     *   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
+     * @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
+
+    /**
+     * Set a custom formatter function like that:
+     * ```
+     *   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.
+     * ```
+     *   cds.log.Logger = ...
+     * ```
+     */
+    Logger: Logger
+
+    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 'debug' level
+     */
+    debug: Log
+
+    /**
+     * Logs with 'info' level
+     */
+    info: Log
+
+    /**
+     * Logs with 'warn' level
+     */
+    warn: Log
+
+    /**
+     * Logs with 'error' level
+     */
+    error: Log
+
+    /**
+     * Logs with default level
+     */
+    log: Log
+
+    /**
+     * @returns whether 'trace' level is active
+     */
+    _trace: boolean
+
+    /**
+     * @returns whether 'debug' level is active
+     */
+     _debug: boolean
+
+    /**
+     * @returns whether 'info' level is active
+     */
+     _info: boolean
+
+    /**
+     * @returns whether 'warn' level is active
+     */
+     _warn: boolean
+
+    /**
+     * @returns whether 'error' level is active
+     */
+     _error: boolean
+
+    /**
+     * Change the format for this logger instance:
+     * ```
+     *   cds.log('foo').setFormat((module, level, ...args) => [ '[', module, ']', ...args ])
+     * ```
+     *
+     * The formatter shall return an array of arguments, which are passed to the logger (for example, `console.log()`)
+     */
+     setFormat(formatter: Formatter)
+}
+
+declare type Formatter = {
+    /**
+     * Custom format function
+     *
+     * @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[]
+}
+
+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
+}
+
+declare enum levels {
+    SILENT = 0, ERROR = 1, WARN = 2, INFO = 3, DEBUG = 4, TRACE = 5, SILLY = 5, VERBOSE = 5
+}

package/apis/models.d.ts

@@ -0,0 +1,180 @@
+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,
+}
+type _options = {
+    flavor?: _flavor,
+    plain?: boolean,
+    docs?: boolean,
+    names?: string,
+    odata?: _odata_options,
+} | _flavor
+
+type JSON = string
+type YAML = string
+type CDL = string
+type SQL = string
+type XML = string
+type EDM = { $version:string }
+type EDMX = XML
+type filename = string
+
+
+export default class cds {
+
+	/**
+	 * The effective CDS model loaded during bootstrapping, which contains all service and entity definitions,
+	 * including required services.
+	 */
+	model?: LinkedCSN
+
+    /**
+     * 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()`.
+     */
+    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[]
+    }
+
+
+    /**
+     * Provides a set of methods to parse a given model, query or expression.
+     * You can also use `cds.compile(csn).to('<output>')` as a fluent variant.
+     */
+    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}]>>
+            }
+        }
+    }
+
+    /**
+     * Loads and parses models from the specified files.
+     * Uses `cds.resolve` to fetch the respective models.
+     * Essentially a shortcut for `cds.compile.to.csn(files)`
+     * @param {string} files - filenames of models or if folder containing models
+     */
+    get(files: '*' | filename | filename[], o?:_options) : Promise<CSN>
+
+    /**
+     * Shortcut for `cds.get(files, 'inferred')`
+     * @param {string} files - filenames of models or if folder containing models
+     */
+    load(files: '*' | filename | filename[], o?:_options) : Promise<CSN>
+
+    /**
+	 * Emitted whenever a model is loaded using cds.load().
+	 */
+	on (event : 'loaded', listener : (model : CSN) => void) : this
+
+
+    /**
+     * Resolves given file or module name(s) to an array of absolute file names.
+     * Uses Node's `require.resolve` internally with the following additions:
+     * - relative names are resolved relative to the current working directory instead of the current JavaScript module; hence, use __dirname if you want to find or load models relative to the current module.
+     * - if no file extension is given, `.csn` and `.cds` will be appended in that order.
+     * @param files - The file or module name(s) of a model or a folder containing models. Specify `'*'` to fetch moels from default locations, i.e. `[ 'db/', 'srv/', 'app/' ]`
+     * @returns An array of absolute file names or `undefined` if none could be resolved.
+     */
+    resolve (files: '*' | filename | filename[]) : filename[] | undefined
+
+    	/**
+	 * Turns the given plain CSN model into a linked model
+	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
+	 */
+	linked(model: CSN): LinkedCSN
+
+	/**
+	 * Turns the given plain CSN model into a reflected model
+	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
+	 */
+	reflect(model: CSN): LinkedCSN
+
+}