@cap-js/cds-types 0.16.0 → 0.17.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_
 
@@ -178,7 +178,27 @@ type Awaitable<T, I> = T & Promise<I>
 
 class Axios {
 
+    /**
+     * @deprecated Used to provide access to an `axios` instance used as HTTP client. From `@cap-js/cds-test` >=1 onwards, it no longer points to
+     * the real `axios` library, but to an emulated lookalike, mostly for backward compatibility.
+     * Install `axios` explicitly as a project dependency if you need the full feature set of it. In that case, the HTTP shortcuts will automatically
+     * use the installed `axios` instead of the emulated version.
+     */
     get axios (): import('axios').AxiosInstance
+
+    /**
+     * Provides default values for HTTP requests. To stay portable across different HTTP clients, it's recommended to only use these options,
+     * which cds.test supports across all clients:
+     * - `baseURL` as defined in Axios
+     * - `auth` as defined in Axios
+     * - `headers` as defined in Fetch API and Axios
+     * - `validateStatus` as defined in Axios (default: status >= 200 && status < 300)
+     *
+     * In addition, you can use all of the config options understood by the underlying HTTP client, that is, for Fetch API,
+     * its RequestInit options, and for Axios, its request config options.
+     */
+    get defaults (): import('axios').AxiosRequestConfig & RequestInit
+
     get: import('axios').AxiosInstance['get'] & TaggedTemplateRequest
 
     put: import('axios').AxiosInstance['put'] & TaggedTemplateRequest
@@ -1040,7 +1060,7 @@ class Decimal extends Float {
 }
 
 /**
- * @beta helper 
+ * @beta helper
  */
 type DeepPartial<T> = T extends object
 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -1352,7 +1372,11 @@ export class EventContext {
 
     id: string
 
-    locale: `${string}_${string}`
+    /**
+     * ISO 639-1 language code, optionally followed by an underscore and ISO 3166-1 alpha-2 country code, e.g. "en" or "en_US".
+     * May be `undefined` if the `AcceptLanguage` header is not set in the incoming request.
+     */
+    locale?: string
 
     timestamp: Date
 
@@ -1362,9 +1386,9 @@ export class EventContext {
 
 }
 
-export interface EventHandler {
+export interface EventHandler<E = any> {
     // (msg : types.EventMessage) : Promise<any> | any | void
-    (req: Request_2): Promise<any> | any | void
+    (req: Request_2<E>): Promise<any> | any | void
 }
 
 /**
@@ -1379,8 +1403,8 @@ export type expr_literal = { '=': string }
 
 type Expression<E extends string | number | bigint | boolean> = `${E}${WS}${Op}${WS}`
 
-type Expressions<L,E> = KVPairs<L, Expression<Exclude<keyof E, symbol>>, ColumnValue> extends true 
-? L 
+type Expressions<L,E> = KVPairs<L, Expression<Exclude<keyof E, symbol>>, ColumnValue> extends true
+? L
 // fallback: allow for any string. Important for when user renamed properties
 : KVPairs<L, Expression<string>, ColumnValue> extends true
 ? L
@@ -1492,7 +1516,7 @@ interface Having<T> {
     having: HavingWhere<this, T>
 }
 
-type HavingWhere<This, E> = 
+type HavingWhere<This, E> =
 /**
 * @param predicate - An object with keys that are valid fields of the target entity and values that are compared to the respective fields.
 * @example
@@ -1502,6 +1526,7 @@ type HavingWhere<This, E> =
 * ```
 */
 ((predicate: Partial<{[column in KeyOfTarget<This extends ConstructedQuery<infer E> ? E : never, never>]: any}>) => This)
+
 /**
 * @param expr - An array of expressions, where every odd element is a valid field of the target entity and every even element is a value that is compared to the respective field.
 * @example
@@ -2213,6 +2238,10 @@ export function on (event: 'listening', listener: (args: { server: import('http'
  	 */
 export function on (event: 'shutdown', listener: () => void): _cds
 
+export function once (event: 'loaded', listener: (model: CSN) => void): _cds
+
+export function once (event: 'connect', listener: (srv: Service) => void): _cds
+
 export function once (event: 'bootstrap', listener: (app: import('express').Application) => void): _cds
 
 export function once (event: 'compile.for.runtime', listener: (model: CSN) => void): _cds
@@ -2221,6 +2250,8 @@ export function once (event: 'compile.to.dbx', listener: (model: CSN) => void):
 
 export function once (event: 'compile.to.edmx', listener: (model: CSN) => void): _cds
 
+export function once (event: 'serving', listener: (srv: Service) => void): _cds
+
 export function once (event: 'served', listener: (all: cds_services) => void): _cds
 
 export function once (event: 'listening', listener: (args: { server: import('http').Server, url: string }) => void): _cds
@@ -2291,6 +2322,31 @@ P extends Record<string, any>[] = Record<string, any>[]
 
 export type predicate = _xpr
 
+/**
+ * @beta helper
+ * @example
+ * ```js
+ * const predicate: PredicateMap<Books> = {
+ *   title: 'foo',
+ *   or: {
+ *     price: { '>': 42 }
+ *   }
+ * }
+ * const result = await SELECT.from(Books).where(predicate)
+ * ```
+ * Note that you _have to_ explicitly type the predicate variable with `PredicateMap<T>`,
+ * as we can not offer this type as overload to `.where()` or `.having()`.
+ */
+type PredicateMap<T> = _PredicateMap<UnwrappedInstanceType<T>>
+
+/** @internal */
+type _PredicateMap<T> = {
+    [k in keyof Partial<T>]: (T[k] | Partial<{ [op in Op]: T[k] }>)
+}
+& { or?: _PredicateMap<T>, and?: _PredicateMap<T> }
+// disallow non-existing properties
+& { [key: string]: never }
+
 type Primitive = string | number | boolean | Date
 
 /** @private */
@@ -2347,6 +2403,7 @@ namespace ql {
     export {
         Query_2 as Query,
         QLExtensions,
+        PredicateMap,
         ConstructedQuery,
         StaticSELECT,
         QL,
@@ -2458,9 +2515,9 @@ export class QueryAPI {
     transaction: QueryAPI['tx']
 
     tx: {
-        (fn: (tx: Transaction) => object): Promise<unknown>,
+        <T>(fn: (tx: Transaction) => T): Promise<Awaited<T>>,
         (context?: object): Transaction,
-        (context: object, fn: (tx: Transaction) => object): Promise<unknown>,
+        <T>(context: object, fn: (tx: Transaction) => T): Promise<Awaited<T>>,
     }
 
 }
@@ -2591,8 +2648,8 @@ export function resolve (files: '*' | filename | filename[]): filename[] | undef
 export interface ResultSet extends Array<object> {}
 
 export interface ResultsHandler {
-    (results: any[], req: Request_2): void
-    (each: any, req: Request_2): void
+    (results: any[], req: Request_2): unknown
+    (each: any, req: Request_2): unknown
 }
 
 export const root: string;
@@ -2928,6 +2985,8 @@ export class Service extends QueryAPI {
     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['__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
+    // event classes, generated by cds-typer
+    on<E extends {new (...args: any): any, kind: 'event'}>(eve: E, handler: EventHandler<InstanceType<E>>): this
     on (eve: types.event, entity: types.target, handler: OnEventHandler): this
     on (eve: types.event, handler: OnEventHandler): this
     on (eve: 'error', handler: OnErrorHandler): this
@@ -3164,12 +3223,24 @@ class Test extends Axios {
      */
     verbose (v: boolean): this
 
+    /**
+     * @deprecated Either use the {@link expect} property here or import `chai` in your test file.
+     */
     get chai (): typeof import('chai')
 
-    get expect (): typeof import('chai').expect
-
+    /**
+     * @deprecated Either use the {@link expect} property here or import `chai.assert` in your test file.
+     */
     get assert (): typeof import('chai').assert
 
+    /**
+     * The `expect` assertion from the `chai` assertion library.
+     *
+     * For Jest, this returns a built-in implementation that covers the most common matchers with the standard `chai` API.
+     * If your tests need more matchers, move to a different test runner such as Vitest, which supports ESM-only modules like `chai`.
+     */
+    get expect (): typeof import('chai').expect
+
     get data (): DataUtil
 
     get cds (): _cds_2
@@ -3234,9 +3305,9 @@ export const transaction: Service['transaction'];
  * @see [docs](https://cap.cloud.sap/docs/node.js/cds-tx)
  */
 export const tx: {
-    (fn: (tx: Transaction) => object): Promise<any>,
+    <T>(fn: (tx: Transaction) => T): Promise<T>,
     (context?: object): Transaction,
-    (context: object, fn: (tx: Transaction) => object): Promise<any>,
+    <T>(context: object, fn: (tx: Transaction) => T): Promise<T>,
 };
 
 export interface type extends Omit<csn.type, 'items'> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-types",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Type definitions for main packages of CAP, like `@sap/cds`",
   "repository": "github:cap-js/cds-types",
   "homepage": "https://cap.cloud.sap/",
@@ -50,14 +50,16 @@
     }
   },
   "devDependencies": {
-    "@cap-js/cds-test": "^0",
+    "@cap-js/cds-test": "^0 || ^1",
     "@cap-js/db-service": "^2.3.0",
     "@microsoft/api-extractor": "^7.52.8",
     "@sap/cds-dk": "^9",
     "@stylistic/eslint-plugin-js": "^4.0.1",
     "@stylistic/eslint-plugin-ts": "^4.0.1",
+    "@types/chai": "^5.2.3",
     "axios": "^1.6.2",
-    "eslint": "^9.2.0",
+    "eslint": "^10",
+    "globals": "^17.5.0",
     "typescript": "^5.4.5",
     "typescript-eslint": "^8.0.0-alpha.51"
   }