@cap-js/cds-types 0.13.0 → 0.15.0

package/dist/cds-types.d.ts

@@ -1,6 +1,6 @@
 declare module '@sap/cds' {
 export * from "@sap/cds-dk";
-
+
 
 export type __any_ = classes.any_
 
@@ -66,9 +66,9 @@ export type __Vector = classes.Vector
 
 class action extends any_<'action' | 'function'> {}
 
-export interface ActionEventHandler<P, R> {
+export interface ActionEventHandler<S, P, R> {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-    (req: Omit<Request_2, 'data'> & { data: P }, next: Function): Promise<R> | R
+    (req: Omit<Request_2, 'data'> & { data: P, subject: S }, next: Function): Promise<R> | R
 }
 
 interface And {
@@ -254,6 +254,7 @@ namespace cds {
         on,
         once,
         exit,
+        error,
         _cds,
         cds_services,
         connect,
@@ -323,6 +324,8 @@ namespace cds {
         Key,
         QueryAPI,
         PropertiesOf,
+        Send,
+        FluentScheduling,
         Service,
         ApplicationService,
         MessagingService,
@@ -358,11 +361,15 @@ namespace cds {
         update,
         transaction,
         db,
+        queued,
+        unqueued,
         outboxed,
         unboxed,
         EventContext,
         Event_2 as Event,
         Request_2 as Request,
+        GetRequest,
+        PostRequest,
         User,
         Anonymous,
         Privileged,
@@ -387,6 +394,7 @@ namespace cds {
         _segment,
         _named,
         val,
+        list,
         xpr,
         _xpr,
         operator,
@@ -434,6 +442,7 @@ namespace cds_2 {
         on,
         once,
         exit,
+        error,
         _cds,
         cds_services,
         connect,
@@ -503,6 +512,8 @@ namespace cds_2 {
         Key,
         QueryAPI,
         PropertiesOf,
+        Send,
+        FluentScheduling,
         Service,
         ApplicationService,
         MessagingService,
@@ -538,11 +549,15 @@ namespace cds_2 {
         update,
         transaction,
         db,
+        queued,
+        unqueued,
         outboxed,
         unboxed,
         EventContext,
         Event_2 as Event,
         Request_2 as Request,
+        GetRequest,
+        PostRequest,
         User,
         Anonymous,
         Privileged,
@@ -567,6 +582,7 @@ namespace cds_2 {
         _segment,
         _named,
         val,
+        list,
         xpr,
         _xpr,
         operator,
@@ -612,6 +628,7 @@ export type CdsFunction = {
     (...args: any[]): any,
     __parameters: object,
     __returns: any,
+    __self?: any,  // the entity the function is bound to, in case of bound functions
 }
 
 /**
@@ -879,6 +896,7 @@ namespace CQN {
         _segment,
         _named,
         val,
+        list,
         xpr,
         _xpr,
         operator,
@@ -1017,6 +1035,18 @@ class Decimal extends Float {
     scale?: number
 }
 
+/**
+ * @beta helper 
+ */
+type DeepPartial<T> = T extends object
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+? T extends Function
+? T
+: T extends Array<infer U>
+? Array<DeepPartial<U>>
+: { [K in keyof T]?: DeepPartial<T[K]> }
+: T
+
 /**
  * Definitions are the central elements of a CDS model.
  */
@@ -1272,6 +1302,17 @@ export namespace env {
     }
 }
 
+/**
+ * @see [capire](https://cap.cloud.sap/docs/node.js/cds-facade#cds-error)
+ */
+export function error (code: number, message: string, details?: {stack?: unknown}, caller?: (...args: any[]) => unknown): Error
+
+export function error (message: string, details?: {code: number, stack?: unknown}, caller?: (...args: any[]) => unknown): Error
+
+export function error (details: {code: number, message: string}, caller?: (...args: any[]) => unknown): Error
+
+export function error (string: TemplateStringsArray, ...args: any[]): Error
+
 export class event extends aspect<'event'> {}
 
 /**
@@ -1328,7 +1369,7 @@ export interface EventHandler {
  */
 export function exit (): void
 
-export type expr = ref | val | xpr | function_call | SELECT_2
+export type expr = ref | val | list | xpr | function_call | SELECT_2
 
 export type expr_literal = { '=': string }
 
@@ -1373,6 +1414,11 @@ export type _flavor = 'parsed' | 'xtended' | 'inferred'
 
 class Float extends number { }
 
+export type FluentScheduling<O extends keyof FluentScheduling = never> = {
+    after: <T = any>(t: number | string, u?: string) => Promise<T> & Omit<FluentScheduling<O | 'after'>, O | 'after'>,
+    every: <T = any>(t: number | string, u?: string) => Promise<T> & Omit<FluentScheduling<O | 'every'>, O | 'every'>,
+}
+
 export const foreach: Service['foreach'];
 
 type Formatter = {
@@ -1404,6 +1450,10 @@ export type function_call = { func: string, args: { [key: string]: any }[] }
  */
 export function get (files: '*' | filename | filename[], o?: _options): Promise<csn.CSN>
 
+export type GetRequest<
+P extends Record<string, any>[]
+> = Request_2<Record<never, never>, P>;
+
 interface GroupBy {
     groupBy: TaggedTemplateQueryPart<this>
     & ((columns: Partial<{[column in KeyOfTarget<this extends ConstructedQuery<infer E> ? E : never, never>]: any}>) => this)
@@ -1417,11 +1467,11 @@ interface GroupBy {
  * @example
  * ```ts
  * import { myAction } from '#cds-models/myService'
- * 
+ *
  * function onMyFunction (req: HandlerFunction<typeof myAction>['parameters']['req']): HandlerFunction<typeof myAction>['returns'] {
  *   ...
  * }
- * 
+ *
  * srv.on(myAction, onMyFunction)
  * ```
  */
@@ -1528,13 +1578,13 @@ interface INSERT_3<T> extends Columns<T>, InUpsert<T> {}
 class INSERT_3<T> extends ConstructedQuery<T> {
     private constructor();
 
-    static into: (<T extends ArrayConstructable> (entity: T, ...entries: SingularInstanceType<T>[]) => INSERT_3<SingularInstanceType<T>>)
-    & (<T extends ArrayConstructable> (entity: T, entries?: SingularInstanceType<T>[]) => INSERT_3<SingularInstanceType<T>>)
+    static into: (<T extends ArrayConstructable> (entity: T, ...entries: DeepPartial<SingularInstanceType<T>>[]) => INSERT_3<SingularInstanceType<T>>)
+    & (<T extends ArrayConstructable> (entity: T, entries?: DeepPartial<SingularInstanceType<T>>[]) => INSERT_3<SingularInstanceType<T>>)
     & (TaggedTemplateQueryPart<INSERT_3<unknown>>)
     & ((entity: EntityDescription, ...entries: Entries[]) => INSERT_3<StaticAny>)
     & ((entity: EntityDescription, entries?: Entries) => INSERT_3<StaticAny>)
-    & (<T> (entity: Constructable<T>, ...entries: T[]) => INSERT_3<T>)
-    & (<T> (entity: Constructable<T>, entries?: T[]) => INSERT_3<T>)
+    & (<T> (entity: Constructable<T>, ...entries: DeepPartial<T>[]) => INSERT_3<T>)
+    & (<T> (entity: Constructable<T>, entries?: DeepPartial<T>[]) => INSERT_3<T>)
 
     from (select: SELECT_3<T>): this
     INSERT: CQN.INSERT['INSERT']
@@ -1556,8 +1606,8 @@ type Intersect<T extends readonly unknown[]> = T extends [infer Head, ...infer T
 interface InUpsert<T> {
     data (block: (e: T) => void): this
 
-    entries (...entries: T[]): this
-    entries (entries: T[]): this
+    entries (...entries: DeepPartial<T>[]): this
+    entries (entries: DeepPartial<T>[]): this
 
     values (...val: (null | Primitive)[]): this
     values (val: (null | Primitive)[]): this
@@ -1799,6 +1849,9 @@ interface LinkedCSN extends Omit<csn.CSN, 'definitions'> {
 
 }
 
+/** @private */
+export type list = { list: any[] }
+
 /**
  * Shortcut for `cds.get(files, 'inferred')`
  * @param files - filenames of models or if folder containing models
@@ -2220,7 +2273,12 @@ type PK = number | string | object
 
 type PluralInstanceType<T extends Constructable> = Array<InstanceType<T>>
 
-export type predicate = UnionsToIntersections<_xpr>
+export type PostRequest<
+D = any,
+P extends Record<string, any>[] = Record<string, any>[]
+> = Request_2<D, P>;
+
+export type predicate = _xpr
 
 type Primitive = string | number | boolean | Date
 
@@ -2416,6 +2474,8 @@ type QueryArtefact = {
 
 }
 
+export const queued: (service: Service) => Service;
+
 export const read: Service['read'];
 
 /** @private */
@@ -2432,9 +2492,12 @@ export class RemoteService extends Service {}
 /**
  * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
  */
-class Request_2<T = any> extends Event_2<T> {
+class Request_2<
+D = any,
+P extends Record<string, any>[] = Record<string, any>[]
+> extends Event_2<D> {
 
-    params: Record<string, any>[]
+    params: P
 
     method: string
 
@@ -2524,8 +2587,6 @@ export const run: Service['run'];
 
 class scalar extends type { }
 
-type Scalarise<A> = A extends Array<infer N> ? N : A
-
 /** @private */
 export type _segment = name | {
     id?: string,
@@ -2563,6 +2624,7 @@ interface SELECT_3<T> extends Where<T>, And, Having<T>, GroupBy, OrderBy<T>, Lim
 
 class SELECT_3<T, Q = SELECT_from> extends ConstructedQuery<T> {
     private constructor();
+    [Symbol.asyncIterator](): AsyncIterableIterator<Unwrap<T>>
 
     static one: SELECT_one & { from: SELECT_one } & { localized: SELECT_one }
 
@@ -2590,6 +2652,32 @@ class SELECT_3<T, Q = SELECT_from> extends ConstructedQuery<T> {
         count?: boolean,
     }
 
+    /**
+     * If a parameter is given, the raw data stream is piped into it.
+     *
+     * If no parameter is given, the raw data stream is returned.
+     * @param stream the writable stream to pipe the raw data into
+     * @see [capire docs](https://cap.cloud.sap/docs/node.js/cds-ql#pipeline)
+     * @since 9.3.0
+     */
+    pipeline(stream: import('node:stream').Writable): Promise<void>
+    /**
+     * If a parameter is given, the raw data stream is piped into it.
+     *
+     * If no parameter is given, the raw data stream is returned.
+     * @see [capire docs](https://cap.cloud.sap/docs/node.js/cds-ql#pipeline)
+     * @since 9.3.0
+     * @returns Readable
+     */
+    pipeline(): Promise<import('node:stream').Readable>
+
+    /**
+     * Calls the given callback function for each row in the result set.
+     * @param cb the callback function to call for each row
+     * @see [capire docs](https://cap.cloud.sap/docs/node.js/cds-ql#foreach)
+     * @since 9.3.0
+     */
+    foreach: (cb: (element: Unwrap<T>) => void) => Promise<void>
 }
 
 type SELECT_from =
@@ -2650,6 +2738,15 @@ TaggedTemplateQueryPart<Awaitable<SELECT_3<_TODO_2, SELECT_one>, InstanceType<_T
 & (<T> (entity: { new(): T }, primaryKey: PK, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T | null>)
 & ((subject: ref) => SELECT_3<_TODO_2>)
 
+export type Send<AddOn = {}> = {
+    <T = any>(event: types.event, path: string, data?: object, headers?: object): Promise<T> & AddOn,
+    <T = any>(event: types.event, data?: object, headers?: object): Promise<T> & AddOn,
+    <T = any>(details: { event: types.event, data?: object, headers?: object }): Promise<T> & AddOn,
+    <T = any>(details: { query: ConstructedQuery<T>, data?: object, headers?: object }): Promise<T> & AddOn,
+    <T = any>(details: { method: types.eventName, path: string, data?: object, headers?: object }): Promise<T> & AddOn,
+    <T = any>(details: { event: types.eventName, entity: linked_2.Definition | string, data?: object, params?: object, headers?: object }): Promise<T> & AddOn,
+}
+
 /**
  	 * Constructs service providers from respective service definitions
  	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-serve)
@@ -2741,21 +2838,27 @@ export class Service extends QueryAPI {
         <P extends ArrayConstructable, R>(event: P, data: PropertiesOf<SingularInstanceType<P>>, headers?: object): Promise<R>,
         <T = any>(event: types.event, data?: object, headers?: object): Promise<T>,
         <T = any>(details: { event: types.event, data?: object, headers?: object }): Promise<T>,
-        <T = any>(event: types.event, data?: object, headers?: object): Promise<T>,
     }
 
     /**
      * Constructs and sends a synchronous request.
      * @see [capire docs](https://cap.cloud.sap/docs/node.js/core-services#srv-send-request)
      */
-    send: {
-        <T = any>(event: types.event, path: string, data?: object, headers?: object): Promise<T>,
-        <T = any>(event: types.event, data?: object, headers?: object): Promise<T>,
-        <T = any>(details: { event: types.event, data?: object, headers?: object }): Promise<T>,
-        <T = any>(details: { query: ConstructedQuery<T>, data?: object, headers?: object }): Promise<T>,
-        <T = any>(details: { method: types.eventName, path: string, data?: object, headers?: object }): Promise<T>,
-        <T = any>(details: { event: types.eventName, entity: linked_2.Definition | string, data?: object, params?: object, headers?: object }): Promise<T>,
-    }
+    send: Send
+
+    /**
+     * @alpha
+     * Constructs and schedules a request for asynchronous processing.
+     * @see [capire docs](https://cap.cloud.sap/docs/node.js/queue#task-scheduling)
+     */
+    schedule: Send<FluentScheduling>
+
+    /**
+     * @alpha
+     * Triggers task processing.
+     * @see [capire docs](https://cap.cloud.sap/docs/node.js/queue#task-processing)
+     */
+    flush(): Promise<void>
 
     /**
      * Constructs and sends a GET request.
@@ -2791,7 +2894,7 @@ export class Service extends QueryAPI {
     }
 
     // The central method to dispatch events
-    dispatch (msg: types.event): Promise<any>
+    dispatch (msg: types.event | Request_2 | types.event[] | Request_2[]): Promise<any>
 
     // FIXME: not yet documented, will come in future version
     // disconnect (tenant?: string): Promise<void>
@@ -2801,8 +2904,8 @@ export class Service extends QueryAPI {
 
     on<T extends ArrayConstructable>(eve: types.event, entity: T | T[], handler: CRUDEventHandler.On<Unwrap<T>>): this
     on<T extends Constructable>(eve: types.event, entity: T | T[], handler: CRUDEventHandler.On<InstanceType<T>>): this
-    on<F extends CdsFunction>(boundAction: F, service: string, handler: ActionEventHandler<F['__parameters'], void | Error | F['__returns']>): this
-    on<F extends CdsFunction>(unboundAction: F, handler: ActionEventHandler<F['__parameters'], void | Error | F['__returns']>): this
+    on<F extends CdsFunction>(boundAction: F, service: string, handler: ActionEventHandler<F['__self'], F['__parameters'], void | Error | F['__returns']>): this
+    on<F extends CdsFunction>(unboundAction: F, handler: ActionEventHandler<F['__self'], F['__parameters'], void | Error | F['__returns']>): this
     on (eve: types.event, entity: types.target, handler: OnEventHandler): this
     on (eve: types.event, handler: OnEventHandler): this
     on (eve: 'error', handler: OnErrorHandler): this
@@ -3147,10 +3250,10 @@ class UInt8 extends Integer { }
 
 export const unboxed: (service: Service) => Service;
 
-type UnionsToIntersections<U> = Array<UnionToIntersection<Scalarise<U>>>
-
 type UnionToIntersection<U> = Partial<(U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never>
 
+export const unqueued: (service: Service) => Service;
+
 type Unwrap<T> = T extends ArrayConstructable
 ? SingularInstanceType<T>
 : T extends Array<infer U>
@@ -3168,7 +3271,10 @@ type UPDATE_2 = { UPDATE: {
     }, }
 export { UPDATE_2 as UPDATE }
 
-interface UPDATE_3<T> extends Where<T>, And, ByKey {}
+interface UPDATE_3<T> extends Where<T>, And, ByKey {
+    set: UpdateSet<this, T>
+    with: UpdateSet<this, T>
+}
 
 class UPDATE_3<T> extends ConstructedQuery<T> {
     private constructor();
@@ -3180,11 +3286,7 @@ class UPDATE_3<T> extends ConstructedQuery<T> {
     & ((entity: EntityDescription | ref | Definition_2, primaryKey?: PK) => UPDATE_3<StaticAny>)
     & (<T> (entity: T, primaryKey?: PK) => UPDATE_3<T>)
 
-    set: UpdateSet<this, T>
-    with: UpdateSet<this, T>
-
     UPDATE: CQN.UPDATE['UPDATE']
-
 }
 
 /**
@@ -3193,9 +3295,9 @@ class UPDATE_3<T> extends ConstructedQuery<T> {
  */
 type UpdateSet<This, T> = TaggedTemplateQueryPart<This>
 // simple value   > title: 'Some Title'
-// qbe expression > stock: { '-=': quantity }  
+// qbe expression > stock: { '-=': quantity }
 // cqn expression > descr: {xpr: [{ref:[descr]}, '||', 'Some addition to descr.']}
-& ((data: {[P in keyof T]?: T[P] | {[op in QbeOp]?: T[P]} | CQN.xpr}) => This)
+& ((data: {[P in keyof T]?: T[P] | DeepPartial<T[P]> | {[op in QbeOp]?: DeepPartial<T[P]>} | CQN.xpr}) => This)
 
 type UPSERT_2 = { UPSERT: {
         into: ref | name,
@@ -3211,13 +3313,13 @@ interface UPSERT_3<T> extends Columns<T>, InUpsert<T> {}
 class UPSERT_3<T> extends ConstructedQuery<T> {
     private constructor();
 
-    static into: (<T extends ArrayConstructable> (entity: T, ...entries: SingularInstanceType<T>[]) => UPSERT_3<SingularInstanceType<T>>)
-    & (<T extends ArrayConstructable> (entity: T, entries?: SingularInstanceType<T>[]) => UPSERT_3<SingularInstanceType<T>>)
+    static into: (<T extends ArrayConstructable> (entity: T, ...entries: DeepPartial<SingularInstanceType<T>>[]) => UPSERT_3<SingularInstanceType<T>>)
+    & (<T extends ArrayConstructable> (entity: T, entries?: DeepPartial<SingularInstanceType<T>>[]) => UPSERT_3<SingularInstanceType<T>>)
     & (TaggedTemplateQueryPart<UPSERT_3<StaticAny>>)
     & ((entity: EntityDescription, ...entries: Entries[]) => UPSERT_3<StaticAny>)
     & ((entity: EntityDescription, entries?: Entries) => UPSERT_3<StaticAny>)
-    & (<T> (entity: Constructable<T>, ...entries: T[]) => UPSERT_3<T>)
-    & (<T> (entity: Constructable<T>, entries?: T[]) => UPSERT_3<T>)
+    & (<T> (entity: Constructable<T>, ...entries: DeepPartial<T>[]) => UPSERT_3<T>)
+    & (<T> (entity: Constructable<T>, entries?: DeepPartial<T>[]) => UPSERT_3<T>)
 
     UPSERT: CQN.UPSERT['UPSERT']
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-types",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Type definitions for main packages of CAP, like `@sap/cds`",
   "repository": "github:cap-js/cds-types",
   "homepage": "https://cap.cloud.sap/",
@@ -51,6 +51,7 @@
   },
   "devDependencies": {
     "@cap-js/cds-test": "^0",
+    "@cap-js/db-service": "^2.3.0",
     "@microsoft/api-extractor": "^7.52.8",
     "@sap/cds-dk": "^9",
     "@stylistic/eslint-plugin-js": "^4.0.1",