@cap-js/cds-types 0.6.3 → 0.6.5

package/README.md

@@ -2,8 +2,17 @@
 
 [![REUSE status](https://api.reuse.software/badge/github.com/cap-js/cds-types)](https://api.reuse.software/info/github.com/cap-js/cds-types)
 ![Unit Tests passing](https://github.com/cap-js/cds-types/actions/workflows/test.yml/badge.svg)
+[![npmjscom](https://img.shields.io/npm/v/@cap-js/cds-types?color=green&label=npmjs.com)](https://www.npmjs.com/package/@cap-js/cds-types)
+![downloads](https://img.shields.io/npm/dw/@cap-js/cds-types)
+[![deps](https://img.shields.io/librariesio/release/npm/@cap-js/cds-types?label=Dependencies)](https://www.npmjs.com/package/@cap-js/cds-types?activeTab=dependencies)
 
-## About this project
+
+[![main test](https://img.shields.io/github/actions/workflow/status/cap-js/cds-types/test.yml?label=main%20test)](https://github.com/cap-js/cds-types/actions/workflows/test.yml?query=branch%3Amain)
+[![main integration test](https://img.shields.io/github/actions/workflow/status/cap-js/cds-types/integration-test.yml?label=main%20integration-test)](https://github.com/cap-js/cds-types/actions/workflows/integration-test.yml?query=branch%3Amain)
+[![main lint](https://img.shields.io/github/actions/workflow/status/cap-js/cds-types/lint.yml?label=main%20lint)](https://github.com/cap-js/cds-types/actions/workflows/lint.yml?query=branch%3Amain)
+
+
+## About this Project
 
 Contains type definitions for the [Node.js SDK](https://cap.cloud.sap/docs/node.js/) of the SAP Cloud Application Programming Model (CAP).
 
@@ -13,6 +22,9 @@ Just install package `@sap/cds` into a Javascript or Typescript project, and the
 
 Find more information on the APIs in the [Node.js SDK documentation](https://cap.cloud.sap/docs/node.js/).
 
+## Note to Microsoft Windows Users
+If you rename your project after you installed the type definitions on Windows, you have to rerun `npm install` to correctly recreate the symlink `node_modules/@types/sap__cds`.
+
 ## Support, Feedback, Contributing
 
 ### Local Setup

package/dist/cds-types.d.ts

@@ -66,6 +66,7 @@ export type __Vector = classes.Vector
 class action extends any_<'action' | 'function'> {}
 
 export interface ActionEventHandler<P, R> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
     (req: Omit<Request_2, 'data'> & { data: P }, next: Function): Promise<R> | R
 }
 
@@ -200,6 +201,7 @@ export type CDL = string
 
 namespace cds {
     export {
+        default_2 as default,
         log,
         debug,
         test,
@@ -536,12 +538,27 @@ export const connect: {
 
     /**
      		 * Connects to a specific datasource.
+     		 * @example 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')
+     	*/
+    to(datasource: 'db', options?: cds_connect_options): Promise<cds.DatabaseService>,
+
+    /**
+     	 * Connects to a specific datasource via a Service subclass
+     	 * @example 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 options.
+     		 * @example cds.connect.to ({ kind:..., impl:... })
      		 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect#cds-connect-to)
      		 */
     to(options: cds_connect_options): Promise<Service>,
@@ -728,6 +745,168 @@ export function debug (name: string): undefined | Log
 
 class Decimal extends Float { }
 
+export namespace default_2 {
+    export {
+        log,
+        debug,
+        test,
+        ql,
+        QLExtensions,
+        csn,
+        delete_ as delete,
+        version,
+        home,
+        root,
+        requires,
+        extend,
+        lazify,
+        lazified,
+        entity,
+        event,
+        type,
+        array,
+        struct,
+        Association,
+        Composition,
+        builtin,
+        on,
+        once,
+        exit,
+        _cds,
+        cds_services,
+        connect,
+        server,
+        serve,
+        services,
+        service,
+        cds_serve_fluent,
+        cds_connect_options,
+        Middleswares,
+        middlewares,
+        env,
+        _TODO,
+        get,
+        load,
+        resolve,
+        reflect,
+        _flavor,
+        _odata_options,
+        _options,
+        JSON_2 as JSON,
+        YAML,
+        CDL,
+        SQL,
+        XML,
+        EDM,
+        EDMX,
+        filename,
+        model,
+        parse,
+        linked,
+        __type,
+        __aspect,
+        __any_,
+        __scalar,
+        __Boolean,
+        __UUID,
+        __String,
+        __LargeString,
+        __Binary,
+        __LargeBinary,
+        __Vector,
+        __Integer,
+        __UInt8,
+        __Int16,
+        __Int32,
+        __Int64,
+        __Float,
+        __Double,
+        __Decimal,
+        __date,
+        __Date,
+        __Time,
+        __DateTime,
+        __TimeStamp,
+        __array,
+        __struct,
+        __context_,
+        __service,
+        __entity,
+        __Association,
+        __Composition,
+        compile,
+        spawn,
+        Key,
+        QueryAPI,
+        Service,
+        ApplicationService,
+        MessagingService,
+        RemoteService,
+        DatabaseService,
+        Transaction,
+        ResultSet,
+        ServiceImpl,
+        EventHandler,
+        OnEventHandler,
+        OnErrorHandler,
+        Partial_2 as Partial,
+        OneOrMany,
+        CdsFunction,
+        TypedRequest,
+        CRUDEventHandler,
+        ActionEventHandler,
+        ResultsHandler,
+        SpawnEvents,
+        SpawnEventEmitter,
+        types,
+        SpawnOptions,
+        context,
+        tx,
+        entities,
+        run,
+        foreach,
+        stream,
+        read,
+        create,
+        insert,
+        update,
+        transaction,
+        db,
+        outboxed,
+        unboxed,
+        EventContext,
+        Event_2 as Event,
+        Request_2 as Request,
+        User,
+        Privileged,
+        utils,
+        Query,
+        SELECT_2 as SELECT,
+        INSERT_2 as INSERT,
+        UPSERT_2 as UPSERT,
+        UPDATE_2 as UPDATE,
+        DELETE_2 as DELETE,
+        CREATE_2 as CREATE,
+        DROP_2 as DROP,
+        primitive,
+        data,
+        name,
+        source,
+        column_expr,
+        predicate,
+        ordering_term,
+        expr,
+        ref,
+        val,
+        xpr,
+        _xpr,
+        operator,
+        function_call,
+        enum_literal,
+        expr_literal
+    }
+}
+
 /**
  * Definitions are the central elements of a CDS model.
  */
@@ -1412,7 +1591,7 @@ type LogFactory = {
     Logger: Logger,
 
     // FIXME
-    /* eslint-disable-next-line @typescript-eslint/ban-types */
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
     winstonLogger (LoggerOptions?: { level?: string, levels?: any, format?: any, transports?: any, exitOnError?: boolean | Function, silent?: boolean }),
 }
 
@@ -1666,6 +1845,7 @@ export interface OnErrorHandler {
 }
 
 export interface OnEventHandler {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
     (req: Request_2, next: Function): Promise<any> | any | void
 }
 
@@ -2282,8 +2462,8 @@ export class Service extends QueryAPI {
     // Provider API
     prepend (fn: ServiceImpl): this
 
-    on<T extends ArrayConstructable>(eve: types.event, entity: T, handler: CRUDEventHandler.On<InstanceType<T>>): this
-    on<T extends Constructable>(eve: types.event, entity: T, handler: CRUDEventHandler.On<Array<InstanceType<T>>>): this
+    on<T extends ArrayConstructable>(eve: types.event, entity: T, handler: CRUDEventHandler.On<Unwrap<T>>): this
+    on<T extends Constructable>(eve: types.event, entity: 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 (eve: types.event, entity: types.target, handler: OnEventHandler): this
@@ -2294,20 +2474,25 @@ export class Service extends QueryAPI {
     // onSucceeded (eve: types.Events, handler: types.EventHandler): this
     // onFailed (eve: types.Events, entity: types.Target, handler: types.EventHandler): this
     // onFailed (eve: types.Events, handler: types.EventHandler): this
-    before<T extends ArrayConstructable>(eve: types.event, entity: T, handler: CRUDEventHandler.Before<InstanceType<T>>): this
-    before<T extends Constructable>(eve: types.event, entity: T, handler: CRUDEventHandler.Before<Array<InstanceType<T>>>): this
+    before<F extends CdsFunction>(boundAction: F, service: string, handler: CRUDEventHandler.Before<F['__parameters'], void | Error | F['__returns']>): this
+    before<F extends CdsFunction>(unboundAction: F, handler: CRUDEventHandler.Before<F['__parameters'], void | Error | F['__returns']>): this
+    before<T extends ArrayConstructable>(eve: types.event, entity: T, handler: CRUDEventHandler.Before<Unwrap<T>>): this
+    before<T extends Constructable>(eve: types.event, entity: T, handler: CRUDEventHandler.Before<InstanceType<T>>): this
     before (eve: types.event, entity: types.target, handler: EventHandler): this
     before (eve: types.event, handler: EventHandler): this
 
     // order relevant:
-    // (2) check if T is arrayable -> use T directly
-    // (3) check if T is scalar -> wrap into array
-    // this streamlines that in _most_ cases, handlers will receive an array.
+    // (2) check if T is arrayable -> unwrap array type
+    // (3) check if T is scalar -> use T directly
+    // this streamlines that in _most_ cases, handlers will receive a single object.
     // _Except_ for after.read handlers (1), which will change its inflection based on T.
-    after<T extends ArrayConstructable>(event: 'READ' | 'EACH', entity: T, handler: CRUDEventHandler.After<Unwrap<T>>): this
-    after<T extends Constructable>(event: 'READ' | 'EACH', entity: T, handler: CRUDEventHandler.After<InstanceType<T>>): this
-    after<T extends ArrayConstructable>(eve: types.event, entity: T, handler: CRUDEventHandler.After<InstanceType<T>>): this
-    after<T extends Constructable>(eve: types.event, entity: T, handler: CRUDEventHandler.After<Array<InstanceType<T>>>): this
+    after<T extends ArrayConstructable>(event: 'READ', entity: T, handler: CRUDEventHandler.After<InstanceType<T>>): this
+    after<T extends ArrayConstructable>(event: 'each', entity: T, handler: CRUDEventHandler.After<Unwrap<T>>): this
+    after<T extends Constructable>(event: 'READ' | 'each', entity: T, handler: CRUDEventHandler.After<InstanceType<T>>): this
+    after<T extends ArrayConstructable>(eve: types.event, entity: T, handler: CRUDEventHandler.After<Unwrap<T>>): this
+    after<T extends Constructable>(eve: types.event, entity: T, handler: CRUDEventHandler.After<InstanceType<T>>): this
+    after<F extends CdsFunction>(boundAction: F, service: string, handler: CRUDEventHandler.After<F['__parameters'], void | Error | F['__returns']>): this
+    after<F extends CdsFunction>(unboundAction: F, handler: CRUDEventHandler.After<F['__parameters'], void | Error | F['__returns']>): this
     after (eve: types.event, entity: types.target, handler: ResultsHandler): this
     after (eve: types.event, handler: ResultsHandler): this
 
@@ -2597,7 +2782,7 @@ export type TypedRequest<T> = Omit<Request_2, 'data'> & { data: T }
 
 export namespace types {
     export type event = eventName | eventName[]
-    export type eventName = string
+    export type eventName = { name: string } | string
     | 'CREATE' | 'READ' | 'UPDATE' | 'DELETE'
     | 'NEW' | 'EDIT' | 'PATCH' | 'SAVE'
     | 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-types",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Type definitions for main packages of CAP, like `@sap/cds`",
   "repository": "github:cap-js/cds-types",
   "homepage": "https://cap.cloud.sap/",
@@ -20,6 +20,7 @@
   ],
   "scripts": {
     "test": "jest --silent",
+    "test:integration": "jest --testMatch \"**/test/**/*.integrationtest.js\"",
     "test:rollup": "npm run rollup; npm run rollup:on; npm run test; npm run rollup:off",
     "rollup": "rm -rf dist/ && mkdir -p etc/ && npx -y @microsoft/api-extractor run --local --verbose && .github/rollup-patch.js",
     "rollup:on": "npm pkg set typings=dist/cds-types.d.ts && [ -d 'apis' ] && mv -- apis -apis || true",
@@ -38,18 +39,18 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.2.0",
-    "@sap/cds": ">=7.5.0",
+    "@sap/cds": ">=8.0.0",
     "@stylistic/eslint-plugin-js": "^2.1.0",
     "@stylistic/eslint-plugin-ts": "^2.1.0",
     "@types/jest": "^29.5.11",
-    "@types/node": "^20",
+    "@types/node": "^22",
     "axios": "^1.6.2",
     "chai": "^4.3.10",
     "eslint": "^9.2.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.1",
     "typescript": "^5.4.5",
-    "typescript-eslint": "^8.0.0-alpha.10",
+    "typescript-eslint": "^8.0.0-alpha.51",
     "winston": "^3.13.0"
   },
   "jest": {

package/scripts/postinstall.js

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
 
-/* eslint-disable @typescript-eslint/no-var-requires*/
 /* eslint-disable no-undef */
+/* eslint-disable @typescript-eslint/no-require-imports */
 const fs = require('node:fs')
-const { join, relative, dirname } = require('node:path')
+const { join, relative, dirname, resolve } = require('node:path')
 
 if (!process.env.INIT_CWD) return
-// TODO: check if were in a local install
+
 const nodeModules = join(process.env.INIT_CWD, 'node_modules')
-if (!fs.existsSync(nodeModules)) return
 const typesDir = join(nodeModules, '@types')
-if (!fs.existsSync(typesDir)) fs.mkdirSync(typesDir)
+// we may have to create node_modules altogether in case of a mono repo
+if (!fs.existsSync(typesDir)) fs.mkdirSync(typesDir, {recursive: true})
 
 // use a relative target, in case the user moves the project
 const target = join(typesDir, 'sap__cds')
-const src = join(nodeModules, '@cap-js/cds-types')
+const src = resolvePkg('@cap-js/cds-types') ?? join(nodeModules, '@cap-js/cds-types')
 const rel = relative(dirname(target), src) // need dirname or we'd land one level above node_modules (one too many "../")
+console.log(`Creating symlink ${target} -> ${rel}`)
 
 // remove the existing symlink
 try {
@@ -31,3 +32,12 @@ try {
     if (e.code !== 'EEXIST') throw e
     // else: symlink exists (the previous unlink hasn't worked), ignore
 }
+
+function resolvePkg(pkg) {
+    try {
+        const pjson = require.resolve(join(pkg, 'package.json'), { paths: [process.env.INIT_CWD] })
+        return resolve(pjson, '..')
+    } catch {
+        return null
+    }
+}