@cap-js/cds-types 0.8.0 → 0.9.0

package/dist/cds-types.d.ts

@@ -76,6 +76,17 @@ interface And {
     & ((...expr: any[]) => this)
 }
 
+/**
+ * Subclass representing unauthenticated users.
+ */
+export class Anonymous extends User {
+
+    constructor ()
+
+    is (): boolean
+
+}
+
 const any: typeof any_;
 
 interface any_ extends csn.any_ {}
@@ -239,7 +250,7 @@ namespace cds {
         service,
         cds_serve_fluent,
         cds_connect_options,
-        Middleswares,
+        Middlewares,
         middlewares,
         app,
         env,
@@ -312,7 +323,8 @@ namespace cds {
         Partial_2 as Partial,
         OneOrMany,
         CdsFunction,
-        TypedRequest,
+        CdsFunctions,
+        HandlerFunction,
         CRUDEventHandler,
         ActionEventHandler,
         ResultsHandler,
@@ -338,6 +350,7 @@ namespace cds {
         Event_2 as Event,
         Request_2 as Request,
         User,
+        Anonymous,
         Privileged,
         utils,
         Query,
@@ -394,12 +407,20 @@ export interface cds_services {
     [name: string]: Service
 }
 
+/**
+ * @beta helper
+ */
 export type CdsFunction = {
     (...args: any[]): any,
     __parameters: object,
     __returns: any,
 }
 
+/**
+ * @beta helper
+ */
+export type CdsFunctions<T> = Pick<T, { [K in keyof T]: T[K] extends CdsFunction ? K : never }[keyof T]>
+
 namespace classes {
     export {
         mixin,
@@ -572,24 +593,33 @@ export const connect: {
 
     /**
      		 * Connects to a specific datasource.
-     		 * @example cds.connect.to ('service')
+     		 * @example await cds.connect.to ('service')
      		 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect#cds-connect-to)
      		 */
     to(datasource: string, options?: cds_connect_options): Promise<Service>,
 
     /**
      	 * Shortcut for 'db' as the primary database returning `cds.DatabaseService`
-     	 * @example cds.connect.to ('db')
+     	 * @example await cds.connect.to ('db')
      	*/
     to(datasource: 'db', options?: cds_connect_options): Promise<cds.DatabaseService>,
 
     /**
      	 * Connects to a specific datasource via a Service subclass
-     	 * @example cds.connect.to (ServiceClass)
+     	 * @example await cds.connect.to (ServiceClass)
      	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect#cds-connect-to)
      	 */
     to<S extends Service>(datasource: {new(): S}, options?: cds_connect_options): Promise<S>,
 
+    /**
+     	 * Connects to a specific datasource via a Service class from cds-typer
+     	 * @example
+     	 *   import ServiceClass from '#cds-models/SomeService'
+     	 *   await cds.connect.to (ServiceClass)
+     	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect#cds-connect-to)
+     	 */
+    to<S>(datasource: S, options?: cds_connect_options): Promise<cds.CdsFunctions<S> & Service>,
+
     /**
      		 * Connects to a specific datasource via options.
      		 * @example cds.connect.to ({ kind:..., impl:... })
@@ -677,9 +707,9 @@ class CREATE_3<T> extends ConstructedQuery<T> {
 }
 
 export namespace CRUDEventHandler {
-    export type Before<P, R = P | void | Error> = (req: TypedRequest<P>) => Promise<R> | R
-    export type On<P, R = P | void | Error> = (req: TypedRequest<P>, next: (...args: any[]) => Promise<R> | R) => Promise<R> | R
-    export type After<P, R = P | void | Error> = (data: undefined | P, req: TypedRequest<P>) => Promise<R> | R
+    export type Before<P, R = P | void | Error> = (req: Request_2<P>) => Promise<R> | R
+    export type On<P, R = P | void | Error> = (req: Request_2<P>, next: (...args: any[]) => Promise<R> | R) => Promise<R> | R
+    export type After<P, R = P | void | Error> = (data: undefined | P, req: Request_2<P>) => Promise<R> | R
 }
 
 /**
@@ -787,13 +817,6 @@ class Decimal extends Float {
     scale?: number
 }
 
-/**
- * Recursively excludes nullability from all properties of T.
- */
-type DeepRequired<T> = { 
-    [K in keyof T]: DeepRequired<T[K]>
-} & Exclude<Required<T>, null>
-
 export namespace default_2 {
     export {
         log,
@@ -831,7 +854,7 @@ export namespace default_2 {
         service,
         cds_serve_fluent,
         cds_connect_options,
-        Middleswares,
+        Middlewares,
         middlewares,
         app,
         env,
@@ -904,7 +927,8 @@ export namespace default_2 {
         Partial_2 as Partial,
         OneOrMany,
         CdsFunction,
-        TypedRequest,
+        CdsFunctions,
+        HandlerFunction,
         CRUDEventHandler,
         ActionEventHandler,
         ResultsHandler,
@@ -930,6 +954,7 @@ export namespace default_2 {
         Event_2 as Event,
         Request_2 as Request,
         User,
+        Anonymous,
         Privileged,
         utils,
         Query,
@@ -1093,6 +1118,12 @@ export const env: {
         [key: string]: any,
     },
     profiles: string[],
+    log: {
+        user: boolean,
+        levels: Record<string, Lowercase<keyof typeof levels>>,
+        als_custom_fields: Record<string, number>,
+        cls_custom_fields: string[],
+    },
     requires: env.Requires,
     folders: {
         app: string,
@@ -1216,11 +1247,11 @@ export class event extends aspect<'event'> {}
 /**
  * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
  */
-class Event_2 extends EventContext {
+class Event_2<T = unknown> extends EventContext {
 
     event: string
 
-    data: any
+    data: T
 
     headers: any
 
@@ -1351,6 +1382,28 @@ interface GroupBy {
     // columns currently not being auto-completed due to complexity
 }
 
+/**
+ * Types herein can be used to type handler functions that are not declared in line:
+ * @example
+ * ```ts
+ * import { myAction } from '#cds-models/myService'
+ * 
+ * function onMyFunction (req: HandlerFunction<typeof myAction>['parameters']['req']): HandlerFunction<typeof myAction>['returns'] {
+ *   ...
+ * }
+ * 
+ * srv.on(myAction, onMyFunction)
+ * ```
+ */
+export type HandlerFunction<F extends CdsFunction> = {
+    parameters: {
+        /** @beta helper */
+        req: Request_2<F['__parameters']>,
+    },
+    /** @beta helper */
+    returns: F['__returns'],
+}
+
 interface Having<T> {
     having: HavingWhere<this, T>
 }
@@ -1396,11 +1449,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?: Entries) => INSERT_3<SingularInstanceType<T>>)
+    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>>)
     & (TaggedTemplateQueryPart<INSERT_3<unknown>>)
+    & ((entity: EntityDescription, ...entries: Entries[]) => INSERT_3<StaticAny>)
     & ((entity: EntityDescription, entries?: Entries) => INSERT_3<StaticAny>)
-    & (<T> (entity: Constructable<T>, entries?: Entries) => INSERT_3<T>)
-    & (<T> (entity: T, entries?: T | Entries) => INSERT_3<T>)
+    & (<T> (entity: Constructable<T>, ...entries: T[]) => INSERT_3<T>)
+    & (<T> (entity: Constructable<T>, entries?: T[]) => INSERT_3<T>)
 
     /**
      * @deprected
@@ -1426,7 +1481,8 @@ type Intersect<T extends readonly unknown[]> = T extends [infer Head, ...infer T
 interface InUpsert<T> {
     data (block: (e: T) => void): this
 
-    entries (...entries: object[]): this
+    entries (...entries: T[]): this
+    entries (entries: T[]): this
 
     values (...val: (null | Primitive)[]): this
     values (val: (null | Primitive)[]): this
@@ -1820,10 +1876,10 @@ type ManagedAssociation = Association & {
 
 export class MessagingService extends Service {}
 
-export type Middleswares = 'context' | 'trace' | 'auth' | 'ctx_model' | string
+export type Middlewares = 'context' | 'trace' | 'auth' | 'ctx_model' | string
 
 export const middlewares: {
-    add: (middleware: import('express').RequestHandler, pos?: XOR<XOR<{ at: number }, { after: Middleswares }>, { before: Middleswares }>) => void,
+    add: (middleware: import('express').RequestHandler, pos?: XOR<XOR<{ at: number }, { after: Middlewares }>, { before: Middlewares }>) => void,
 };
 
 /**
@@ -1957,7 +2013,7 @@ export function on (event: 'loaded', listener: (model: CSN) => void): _cds
 export function on (event: 'connect', listener: (srv: Service) => void): _cds
 
 /**
- 	 * Emitted at the very beginning of the bootsrapping process, when the
+ 	 * Emitted at the very beginning of the bootstrapping process, when the
  	 * express application has been constructed but no middlewares or routes
  	 * added yet.
  	 */
@@ -2077,6 +2133,8 @@ type Projection<T> = (e: QLExtensions<T extends ArrayConstructable ? SingularIns
  */
 type Protocol = 'odata' | 'rest'
 
+type QbeOp = '=' | '-=' | '+=' | '*=' | '/=' | '%='
+
 class QL<T> {
 
     SELECT: StaticSELECT<T>
@@ -2088,7 +2146,7 @@ class QL<T> {
     & ((...entries: object[]) => UPSERT_3<T>) & ((entries: object[]) => UPSERT_3<T>)
 
     UPDATE: typeof UPDATE_3<T>
-    & typeof UPDATE_3.entity<_TODO_2>
+    & typeof UPDATE_3.entity
 
     DELETE: typeof DELETE_3<T>
     & ((...entries: object[]) => DELETE_3<T>) & ((entries: object[]) => DELETE_3<T>)
@@ -2117,7 +2175,7 @@ namespace ql {
 }
 export { ql }
 
-export type QLExtensions<T> = T extends QLExtensions_<any> ? T : QLExtensions_<DeepRequired<T>>
+export type QLExtensions<T> = T extends QLExtensions_<any> ? T : QLExtensions_<Required<T>>
 
 /**
  * QLExtensions are properties that are attached to entities in CQL contexts.
@@ -2144,6 +2202,7 @@ export class QueryAPI {
     read: {
         <T extends ArrayConstructable>(entity: T, key?: Key): Awaitable<SELECT_3<T>, InstanceType<T>>,
         <T>(entity: linked_2.Definition | string, key?: Key): SELECT_3<T>,
+        (entity: ref, key?: Key): SELECT_3<unknown>,
     }
 
     /**
@@ -2256,7 +2315,7 @@ export class RemoteService extends Service {}
 /**
  * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
  */
-class Request_2 extends Event_2 {
+class Request_2<T = any> extends Event_2<T> {
 
     params: (string | object)[]
 
@@ -2436,7 +2495,7 @@ TaggedTemplateQueryPart<Awaitable<SELECT_3<_TODO_2>, InstanceType<_TODO_2>>>
 &
 (<E extends ArrayConstructable>
 (entityType: E, primaryKey: PK, projection?: Projection<SingularInstanceType<E>>)
-=> Awaitable<SELECT_3<SingularInstanceType<E>>, SingularInstanceType<E>>) // when specifying a key, we expect a single element as result
+=> Awaitable<SELECT_3<SingularInstanceType<E>>, SingularInstanceType<E> | null>) // when specifying a key, we expect a single element as result
 // calling with definition
 & (<T>(entity: EntityDescription, primaryKey?: PK, projection?: Projection<T>) => SELECT_3<T>)
 // calling with concrete list
@@ -2470,17 +2529,17 @@ TaggedTemplateQueryPart<Awaitable<SELECT_3<_TODO_2, SELECT_one>, InstanceType<_T
 // calling with class
 (<T extends ArrayConstructable>
 (entityType: T, projection?: Projection<QLExtensions<SingularInstanceType<T>>>)
-=> Awaitable<SELECT_3<SingularInstanceType<T>, SELECT_one>, SingularInstanceType<T>>)
+=> Awaitable<SELECT_3<SingularInstanceType<T>, SELECT_one>, SingularInstanceType<T> | null>)
 &
 (<T extends ArrayConstructable>
 (entityType: T, primaryKey: PK, projection?: Projection<QLExtensions<SingularInstanceType<T>>>)
-=> Awaitable<SELECT_3<SingularInstanceType<T>, SELECT_one>, SingularInstanceType<T>>)
+=> Awaitable<SELECT_3<SingularInstanceType<T>, SELECT_one>, SingularInstanceType<T> | null>)
 
 & ((entity: EntityDescription, primaryKey?: PK, projection?: Projection<unknown>) => SELECT_3<_TODO_2, SELECT_one>)
-& (<T> (entity: T[], projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T>)
-& (<T> (entity: T[], primaryKey: PK, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T>)
-& (<T> (entity: { new(): T }, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T>)
-& (<T> (entity: { new(): T }, primaryKey: PK, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T>)
+& (<T> (entity: T[], projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T | null>)
+& (<T> (entity: T[], primaryKey: PK, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T | null>)
+& (<T> (entity: { new(): T }, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T | null>)
+& (<T> (entity: { new(): T }, primaryKey: PK, projection?: Projection<T>) => Awaitable<SELECT_3<T, SELECT_one>, T | null>)
 & ((subject: ref) => SELECT_3<_TODO_2>)
 
 /**
@@ -2562,7 +2621,7 @@ export class Service extends QueryAPI {
 
     /**
      * Constructs and emits an asynchronous event.
-     * @see [capire docs](https://cap.cloud.sap/docs/core-services#srv-emit-event)
+     * @see [capire docs](https://cap.cloud.sap/docs/node.js/core-services#srv-emit-event)
      */
     emit: {
         <T = any>(details: { event: types.event, data?: object, headers?: object }): Promise<T>,
@@ -2945,15 +3004,13 @@ export class type<K extends kinds = 'type'> extends any_<K> { }
 interface type_2 extends any__2 {
     type?: 'cds.Boolean' |
     'cds.UUID' | 'cds.String' | 'cds.LargeString' | 'cds.Binary' | 'cds.LargeBinary' | 'cds.Vector' |
-    'cds.Integer' | 'cds.UInt8' | 'cds.Int16' | 'cds.Int32' | 'cds.Int64' | 'cds.Float' | 'cds.Double' | 'cds.Decimal' |
+    'cds.Integer' | 'cds.UInt8' | 'cds.Int16' | 'cds.Int32' | 'cds.Int64' | 'cds.Double' | 'cds.Decimal' |
     'cds.Date' | 'cds.Time' | 'cds.DateTime' | 'cds.Timestamp' |
     'cds.Association' | 'cds.Composition' |
     FQN & Record<never,never> // allow any other CDS type as well (e.g. 'User')
     items?: type_2
 }
 
-export type TypedRequest<T> = Omit<Request_2, 'data'> & { data: T }
-
 export namespace types {
     export type event = eventName | eventName[]
     export type eventName = { name: string } | string
@@ -2994,29 +3051,30 @@ interface UPDATE_3<T> extends Where<T>, And, ByKey {}
 class UPDATE_3<T> extends ConstructedQuery<T> {
     private constructor();
 
-    // cds-typer plural
-    // FIXME: this returned UPDATE<SingularInstanceType<T>> before. should UPDATE<Books>.entity(...) return Book or Books?
-    static entity<T extends ArrayConstructable> (entity: T, primaryKey?: PK): UPDATE_3<InstanceType<T>>
-
-    static entity (entity: EntityDescription, primaryKey?: PK): UPDATE_3<StaticAny>
+    static entity: (TaggedTemplateQueryPart<UPDATE_3<StaticAny>>)
+    // UPDATE<SingularInstanceType<T>> is used here so type inference in set/with has the property keys of the singular type
+    & (<T extends ArrayConstructable> (entity: T, primaryKey?: PK) => UPDATE_3<SingularInstanceType<T>>)
+    & (<T extends Constructable> (entity: T, primaryKey?: PK) => UPDATE_3<InstanceType<T>>)
+    & ((entity: EntityDescription | ref | Definition_2, primaryKey?: PK) => UPDATE_3<StaticAny>)
+    & (<T> (entity: T, primaryKey?: PK) => UPDATE_3<T>)
 
-    static entity<T extends Constructable> (entity: T, primaryKey?: PK): UPDATE_3<T>
-
-    // currently no easy way to restrict T from being a primitive type
-    static entity<T> (entity: T, primaryKey?: PK): UPDATE_3<T>
-
-    // with (block: (e:T)=>void) : this
-    // set (block: (e:T)=>void) : this
-    set: TaggedTemplateQueryPart<this>
-    & ((data: object) => this);
-
-    with: TaggedTemplateQueryPart<this>
-    & ((data: object) => this)
+    set: UpdateSet<this, T>
+    with: UpdateSet<this, T>
 
     UPDATE: CQN.UPDATE['UPDATE']
 
 }
 
+/**
+ * Represents updatable block that can be passed to either `.set` or `.with`
+ * of an `UPDATE` query
+ */
+type UpdateSet<This, T> = TaggedTemplateQueryPart<This>
+// simple value   > title: 'Some Title'
+// 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)
+
 type UPSERT_2 = { UPSERT: {
         into: ref | name,
         columns: string[],
@@ -3031,13 +3089,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?: Entries) => UPSERT_3<SingularInstanceType<T>>)
+    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>>)
     & (TaggedTemplateQueryPart<UPSERT_3<StaticAny>>)
+    & ((entity: EntityDescription, ...entries: Entries[]) => UPSERT_3<StaticAny>)
     & ((entity: EntityDescription, entries?: Entries) => UPSERT_3<StaticAny>)
-    & (<T> (entity: Constructable<T>, entries?: Entries) => UPSERT_3<T>)
-    // currently no easy way to restrict T to non-primitives
-    & (<T> (entity: T, entries?: T | Entries) => UPSERT_3<T>)
-
+    & (<T> (entity: Constructable<T>, ...entries: T[]) => UPSERT_3<T>)
+    & (<T> (entity: Constructable<T>, entries?: T[]) => UPSERT_3<T>)
 
     UPSERT: CQN.UPSERT['UPSERT']
 
@@ -3066,8 +3124,16 @@ export class User {
 
     roles: Array<string> | Record<string, string>
 
+    static Anonymous: typeof Anonymous
+
+    static anonymous: Anonymous
+
     static Privileged: typeof Privileged
 
+    static privileged: Privileged
+
+    static default: User
+
     is (role: string): boolean
 
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-types",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Type definitions for main packages of CAP, like `@sap/cds`",
   "repository": "github:cap-js/cds-types",
   "homepage": "https://cap.cloud.sap/",
@@ -33,10 +33,8 @@
     "dependencies": "node ./scripts/postinstall.js"
   },
   "peerDependencies": {
-    "@sap/cds": "^8.0.0"
-  },
-  "dependencies": {
-    "@types/express": "^4.17.21"
+    "@sap/cds": "^8.0.0",
+    "@types/express": ">=4"
   },
   "devDependencies": {
     "@eslint/js": "^9.2.0",