@sdflc/backend-helpers 1.0.112 → 1.0.114
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1422 -146
- package/build/BaseController.d.ts +20 -0
- package/build/BaseController.js +64 -0
- package/build/BaseCore.d.ts +586 -33
- package/build/BaseCore.js +821 -127
- package/build/BaseExternalApiGateway.d.ts +16 -0
- package/build/BaseExternalApiGateway.js +54 -0
- package/build/BaseGateway.d.ts +455 -17
- package/build/BaseGateway.js +502 -56
- package/build/BaseRestApiCrudController.d.ts +37 -0
- package/build/BaseRestApiCrudController.js +134 -0
- package/build/DataCache.d.ts +116 -5
- package/build/DataCache.js +144 -22
- package/build/Database.d.ts +165 -4
- package/build/Database.js +224 -51
- package/build/DbMigratorAndSeeder.d.ts +127 -26
- package/build/DbMigratorAndSeeder.js +180 -69
- package/build/IpRateLimiter.d.ts +105 -0
- package/build/IpRateLimiter.js +104 -0
- package/build/RedisDataLoader.d.ts +144 -21
- package/build/RedisDataLoader.js +178 -49
- package/build/apiContext.d.ts +0 -8
- package/build/apiContext.js +30 -32
- package/build/checkItHelpers.d.ts +32 -0
- package/build/checkItHelpers.js +73 -7
- package/build/commonValidators.d.ts +107 -16
- package/build/commonValidators.js +211 -106
- package/build/configBuilder.d.ts +23 -0
- package/build/configBuilder.js +73 -0
- package/build/constants.d.ts +134 -17
- package/build/constants.js +95 -15
- package/build/dbHelpers.d.ts +89 -29
- package/build/dbHelpers.js +175 -86
- package/build/dbSeeder.d.ts +10 -1
- package/build/dbSeeder.js +80 -15
- package/build/dbTableHelpers.d.ts +122 -5
- package/build/dbTableHelpers.js +151 -13
- package/build/downloadHelpers.d.ts +24 -1
- package/build/downloadHelpers.js +51 -21
- package/build/esm/BaseController.d.ts +20 -0
- package/build/esm/BaseController.js +58 -0
- package/build/esm/BaseCore.d.ts +586 -33
- package/build/esm/BaseCore.js +812 -118
- package/build/esm/BaseExternalApiGateway.d.ts +16 -0
- package/build/esm/BaseExternalApiGateway.js +48 -0
- package/build/esm/BaseGateway.d.ts +455 -17
- package/build/esm/BaseGateway.js +503 -57
- package/build/esm/BaseRestApiCrudController.d.ts +37 -0
- package/build/esm/BaseRestApiCrudController.js +131 -0
- package/build/esm/DataCache.d.ts +116 -5
- package/build/esm/DataCache.js +142 -20
- package/build/esm/Database.d.ts +165 -4
- package/build/esm/Database.js +224 -51
- package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
- package/build/esm/DbMigratorAndSeeder.js +184 -71
- package/build/esm/IpRateLimiter.d.ts +105 -0
- package/build/esm/IpRateLimiter.js +100 -0
- package/build/esm/RedisDataLoader.d.ts +144 -21
- package/build/esm/RedisDataLoader.js +179 -50
- package/build/esm/apiContext.d.ts +0 -8
- package/build/esm/apiContext.js +30 -32
- package/build/esm/checkItHelpers.d.ts +32 -0
- package/build/esm/checkItHelpers.js +73 -7
- package/build/esm/commonValidators.d.ts +107 -16
- package/build/esm/commonValidators.js +209 -105
- package/build/esm/configBuilder.d.ts +23 -0
- package/build/esm/configBuilder.js +69 -0
- package/build/esm/constants.d.ts +134 -17
- package/build/esm/constants.js +94 -14
- package/build/esm/dbHelpers.d.ts +89 -29
- package/build/esm/dbHelpers.js +171 -81
- package/build/esm/dbSeeder.d.ts +10 -1
- package/build/esm/dbSeeder.js +81 -16
- package/build/esm/dbTableHelpers.d.ts +122 -5
- package/build/esm/dbTableHelpers.js +152 -14
- package/build/esm/downloadHelpers.d.ts +24 -1
- package/build/esm/downloadHelpers.js +51 -21
- package/build/esm/index.d.ts +6 -2
- package/build/esm/index.js +6 -2
- package/build/esm/interfaces/ApiContext.d.ts +33 -3
- package/build/esm/interfaces/ApiContext.js +1 -0
- package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/esm/interfaces/BaseCorePropsInterface.d.ts +146 -9
- package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
- package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/esm/interfaces/BuildConfigOptions.js +1 -0
- package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/esm/interfaces/CacheInterface.d.ts +18 -1
- package/build/esm/interfaces/CacheInterface.js +1 -0
- package/build/esm/interfaces/CoreActionInterface.d.ts +60 -0
- package/build/esm/interfaces/CoreActionInterface.js +1 -0
- package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
- package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/esm/interfaces/DatabaseOptions.js +1 -0
- package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
- package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/esm/interfaces/ListArgsInterface.js +1 -0
- package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
- package/build/esm/interfaces/LoaderInterface.js +1 -0
- package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
- package/build/esm/interfaces/UserTokenParams.js +1 -0
- package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/esm/interfaces/index.d.ts +4 -0
- package/build/esm/interfaces/index.js +4 -0
- package/build/esm/knexConfigBuilder.d.ts +25 -0
- package/build/esm/knexConfigBuilder.js +100 -36
- package/build/esm/parseIds.d.ts +6 -0
- package/build/esm/parseIds.js +13 -0
- package/build/esm/passwordHelpers.d.ts +22 -0
- package/build/esm/passwordHelpers.js +40 -8
- package/build/esm/redisClient.d.ts +57 -4
- package/build/esm/redisClient.js +40 -54
- package/build/esm/resolveClientIp.d.ts +15 -0
- package/build/esm/resolveClientIp.js +34 -0
- package/build/esm/resolversHelpers.d.ts +21 -1
- package/build/esm/resolversHelpers.js +48 -26
- package/build/esm/userToken.d.ts +50 -1
- package/build/esm/userToken.js +85 -20
- package/build/esm/utils.d.ts +20 -2
- package/build/esm/utils.js +23 -13
- package/build/index.d.ts +6 -2
- package/build/index.js +6 -2
- package/build/interfaces/ApiContext.d.ts +33 -3
- package/build/interfaces/ApiContext.js +1 -0
- package/build/interfaces/ApiContextInterface.d.ts +1 -1
- package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
- package/build/interfaces/BaseControllerPropsInterface.js +2 -0
- package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
- package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
- package/build/interfaces/BaseCorePropsInterface.d.ts +146 -9
- package/build/interfaces/BaseCorePropsInterface.js +1 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
- package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
- package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
- package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
- package/build/interfaces/BuildConfigOptions.d.ts +18 -0
- package/build/interfaces/BuildConfigOptions.js +1 -0
- package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
- package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
- package/build/interfaces/CacheInterface.d.ts +18 -1
- package/build/interfaces/CacheInterface.js +1 -0
- package/build/interfaces/CoreActionInterface.d.ts +60 -0
- package/build/interfaces/CoreActionInterface.js +1 -0
- package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
- package/build/interfaces/CreateUserTokenArgs.js +1 -0
- package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
- package/build/interfaces/DataCachePropsInterface.js +3 -0
- package/build/interfaces/DatabaseOptions.d.ts +24 -10
- package/build/interfaces/DatabaseOptions.js +1 -0
- package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
- package/build/interfaces/DatabaseReadInterface.js +1 -0
- package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
- package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
- package/build/interfaces/DownloadFileArgs.d.ts +21 -2
- package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
- package/build/interfaces/ExtractCredentialsArgs.js +1 -0
- package/build/interfaces/ListArgsInterface.d.ts +18 -0
- package/build/interfaces/ListArgsInterface.js +1 -0
- package/build/interfaces/LoaderInterface.d.ts +36 -1
- package/build/interfaces/LoaderInterface.js +1 -0
- package/build/interfaces/UserTokenParams.d.ts +23 -5
- package/build/interfaces/UserTokenParams.js +1 -0
- package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
- package/build/interfaces/VerifyUserTokenArgs.js +1 -0
- package/build/interfaces/index.d.ts +4 -0
- package/build/interfaces/index.js +4 -0
- package/build/knexConfigBuilder.d.ts +25 -0
- package/build/knexConfigBuilder.js +99 -35
- package/build/parseIds.d.ts +6 -0
- package/build/parseIds.js +17 -0
- package/build/passwordHelpers.d.ts +22 -0
- package/build/passwordHelpers.js +40 -8
- package/build/redisClient.d.ts +57 -4
- package/build/redisClient.js +40 -54
- package/build/resolveClientIp.d.ts +15 -0
- package/build/resolveClientIp.js +38 -0
- package/build/resolversHelpers.d.ts +21 -1
- package/build/resolversHelpers.js +48 -26
- package/build/userToken.d.ts +50 -1
- package/build/userToken.js +85 -20
- package/build/utils.d.ts +20 -2
- package/build/utils.js +24 -16
- package/package.json +19 -18
- package/build/baseController.d.ts +0 -17
- package/build/baseController.js +0 -64
- package/build/configBulder.d.ts +0 -2
- package/build/configBulder.js +0 -36
- package/build/esm/baseController.d.ts +0 -17
- package/build/esm/baseController.js +0 -58
- package/build/esm/configBulder.d.ts +0 -2
- package/build/esm/configBulder.js +0 -32
|
@@ -1,26 +1,40 @@
|
|
|
1
|
-
import { Logger } from '@sdflc/utils';
|
|
2
1
|
/**
|
|
3
|
-
*
|
|
2
|
+
* Options for initialising a Database instance.
|
|
3
|
+
*
|
|
4
|
+
* Connection pool deduplication:
|
|
5
|
+
* Database instances sharing the same host/port/user/database/schema
|
|
6
|
+
* combination reuse a single underlying Knex connection pool. Creating
|
|
7
|
+
* a new Database instance does not open a new pool if one already exists.
|
|
4
8
|
*/
|
|
5
9
|
export interface DatabaseOptions {
|
|
6
10
|
/**
|
|
7
|
-
* Knex configuration object
|
|
11
|
+
* Knex configuration object. Required — must include at minimum a
|
|
12
|
+
* `client` and `connection` property.
|
|
13
|
+
* See: https://knexjs.org/guide/#configuration-options
|
|
8
14
|
*/
|
|
9
15
|
knexConfig: any;
|
|
10
16
|
/**
|
|
11
|
-
* Database type
|
|
17
|
+
* Database driver type (e.g. 'pg', 'mysql2', 'sqlite3').
|
|
18
|
+
* Optional — falls back to `knexConfig.client` if not provided.
|
|
12
19
|
*/
|
|
13
|
-
dbType
|
|
20
|
+
dbType?: string;
|
|
14
21
|
/**
|
|
15
|
-
*
|
|
22
|
+
* Database schema name to scope all queries via withSchema().
|
|
23
|
+
* Optional — if not provided, no schema scoping is applied and
|
|
24
|
+
* queries run against the default schema for the connection.
|
|
16
25
|
*/
|
|
17
|
-
dbSchema
|
|
26
|
+
dbSchema?: string;
|
|
18
27
|
/**
|
|
19
|
-
* Knex transaction object
|
|
28
|
+
* An existing Knex transaction object to use for all queries on this
|
|
29
|
+
* instance. Optional — if not provided, queries run outside a transaction
|
|
30
|
+
* until `startTransaction()` is called.
|
|
20
31
|
*/
|
|
21
32
|
trx?: any;
|
|
22
33
|
/**
|
|
23
|
-
* Logger for
|
|
34
|
+
* Logger for debug/error output. Optional — falls back to a new Logger
|
|
35
|
+
* at ERROR level if not provided or if the value fails the isLogger()
|
|
36
|
+
* duck-type check. Typed as `any` to avoid instanceof failures when the
|
|
37
|
+
* consuming app has a different installed version of @sdflc/utils.
|
|
24
38
|
*/
|
|
25
|
-
logger?:
|
|
39
|
+
logger?: any;
|
|
26
40
|
}
|
|
@@ -1,14 +1,69 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Arguments for the Database.read() convenience method.
|
|
3
|
+
* Provides a structured alternative to building a Knex query manually
|
|
4
|
+
* for simple SELECT operations with optional filtering, mapping, and
|
|
5
|
+
* computed field support.
|
|
3
6
|
*/
|
|
4
7
|
export interface DatabaseReadInterface {
|
|
8
|
+
/**
|
|
9
|
+
* Table name to query. Passed directly to getBuilder().
|
|
10
|
+
*/
|
|
5
11
|
table?: string;
|
|
12
|
+
/**
|
|
13
|
+
* Columns to SELECT. Defaults to '*' if not provided or empty.
|
|
14
|
+
*/
|
|
6
15
|
selectFields?: string[];
|
|
16
|
+
/**
|
|
17
|
+
* Sort configuration. Declared for interface completeness but NOT
|
|
18
|
+
* currently applied inside read() — sorting must be handled by the
|
|
19
|
+
* caller via createLimitOffsetSortBy() before calling read(), or
|
|
20
|
+
* via extendQuery(). This field is a no-op in the current implementation.
|
|
21
|
+
*/
|
|
7
22
|
sortBy?: any;
|
|
23
|
+
/**
|
|
24
|
+
* Object passed to Knex's .where() for equality filtering.
|
|
25
|
+
* e.g. `{ status: 'active', spaceId: '123' }`
|
|
26
|
+
*/
|
|
8
27
|
where?: any;
|
|
9
|
-
|
|
28
|
+
/**
|
|
29
|
+
* Configures a Knex .whereIn() clause.
|
|
30
|
+
* e.g. `{ field: 'id', values: ['a', 'b', 'c'] }`
|
|
31
|
+
*/
|
|
32
|
+
whereIn?: {
|
|
33
|
+
field: string;
|
|
34
|
+
values: any[];
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* Optional async function to extend the Knex query with additional
|
|
38
|
+
* clauses (JOINs, subqueries, additional WHERE conditions, etc.)
|
|
39
|
+
* before it is executed. Receives the live Knex query builder instance.
|
|
40
|
+
*
|
|
41
|
+
* @param query The Knex query builder, mutated in place
|
|
42
|
+
*/
|
|
10
43
|
extendQuery?(query: any): any;
|
|
44
|
+
/**
|
|
45
|
+
* When set, results are reduced into a `Record<string, row>` keyed by
|
|
46
|
+
* the camelCase value of this field on each row, processed through
|
|
47
|
+
* the `buildKey` function. Useful for building lookup maps.
|
|
48
|
+
* e.g. `mapBy: 'id'` produces `{ 'abc-123': row, ... }`
|
|
49
|
+
*/
|
|
11
50
|
mapBy?: string;
|
|
51
|
+
/**
|
|
52
|
+
* Computed field descriptors applied to each result row after the query.
|
|
53
|
+
* Each entry is `{ name: string, value: any | ((row) => any) }`.
|
|
54
|
+
* If `value` is a function it receives the row and returns the computed value.
|
|
55
|
+
* Entries missing `name` are skipped with a warning.
|
|
56
|
+
*/
|
|
12
57
|
calculated?: any[];
|
|
13
|
-
|
|
58
|
+
/**
|
|
59
|
+
* Custom key builder for the mapBy lookup map.
|
|
60
|
+
* Receives the raw field value from each row and returns the string key.
|
|
61
|
+
* Defaults to buildKey from @sdflc/utils if not provided.
|
|
62
|
+
* Typed as `any` input since the field value may not be a string
|
|
63
|
+
* (e.g. UUID objects, numbers, composite values).
|
|
64
|
+
*
|
|
65
|
+
* Fix: was typed as `(key: string) => string` but the input is the raw
|
|
66
|
+
* field value which may be of any type.
|
|
67
|
+
*/
|
|
68
|
+
buildKey?(key: any): string;
|
|
14
69
|
}
|
|
@@ -1,9 +1,40 @@
|
|
|
1
1
|
export interface DbFieldAddDefaultInterface {
|
|
2
|
-
|
|
3
|
-
|
|
2
|
+
/**
|
|
3
|
+
* When true, adds a `status` integer column (indexed) with default STATUSES.ACTIVE.
|
|
4
|
+
*/
|
|
4
5
|
addStatus?: boolean;
|
|
5
|
-
|
|
6
|
-
|
|
6
|
+
/**
|
|
7
|
+
* Custom comment for the status column.
|
|
8
|
+
* Defaults to a description of all known status values.
|
|
9
|
+
*/
|
|
7
10
|
statusComment?: string;
|
|
11
|
+
/**
|
|
12
|
+
* When true, adds a `version` integer column defaulting to 0.
|
|
13
|
+
* Used for optimistic locking — incremented on each update.
|
|
14
|
+
*/
|
|
15
|
+
addVersion?: boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Custom comment for the version column.
|
|
18
|
+
*/
|
|
8
19
|
versionComment?: string;
|
|
20
|
+
/**
|
|
21
|
+
* When true, adds created_by, updated_by, and removed_by UUID columns.
|
|
22
|
+
* These reference the user who performed each operation.
|
|
23
|
+
* removed_by is always added alongside the others for schema consistency,
|
|
24
|
+
* even if the table uses hard deletes.
|
|
25
|
+
*/
|
|
26
|
+
addUserInfo?: boolean;
|
|
27
|
+
/**
|
|
28
|
+
* When true, skips adding all timestamp-related columns:
|
|
29
|
+
* created_at, updated_at, removed_at, and removed_at_str.
|
|
30
|
+
* Also skips their associated indexes.
|
|
31
|
+
* Defaults to false (timestamps are added by default).
|
|
32
|
+
*/
|
|
33
|
+
skipTimestamps?: boolean;
|
|
34
|
+
/**
|
|
35
|
+
* When true, skips adding the `removed_at_str` column and its index.
|
|
36
|
+
* Has no effect when `skipTimestamps` is also true.
|
|
37
|
+
* Defaults to false (removed_at_str is added by default with timestamps).
|
|
38
|
+
*/
|
|
39
|
+
skipRemovedAtStr?: boolean;
|
|
9
40
|
}
|
|
@@ -1,6 +1,25 @@
|
|
|
1
|
+
import type { Writable } from 'stream';
|
|
1
2
|
export interface DownloadFileArgs {
|
|
3
|
+
/**
|
|
4
|
+
* URL of the file to download. Required.
|
|
5
|
+
*/
|
|
2
6
|
url: string;
|
|
3
|
-
|
|
7
|
+
/**
|
|
8
|
+
* Local file name to save as. Optional — if not provided, the file name
|
|
9
|
+
* is derived from the last path segment of the URL, or `<hostname>.html`
|
|
10
|
+
* for root URLs.
|
|
11
|
+
*/
|
|
12
|
+
fileName?: string;
|
|
13
|
+
/**
|
|
14
|
+
* Absolute path to the folder where the file should be saved.
|
|
15
|
+
* Optional — defaults to process.cwd() if not provided.
|
|
16
|
+
*/
|
|
4
17
|
folder?: string;
|
|
5
|
-
|
|
18
|
+
/**
|
|
19
|
+
* Custom writable stream to pipe the download into.
|
|
20
|
+
* Optional — if not provided, a write stream to `folder/fileName` is created.
|
|
21
|
+
* Use this for in-memory targets, cloud storage uploads, or other
|
|
22
|
+
* non-filesystem destinations.
|
|
23
|
+
*/
|
|
24
|
+
stream?: Writable;
|
|
6
25
|
}
|
|
@@ -1,19 +1,30 @@
|
|
|
1
1
|
export interface ExtractCredentialsArgs {
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
3
|
+
* Express request object. Used to read cookies and headers.
|
|
4
4
|
*/
|
|
5
5
|
req: any;
|
|
6
6
|
/**
|
|
7
|
-
*
|
|
7
|
+
* The resolved space object for the current request.
|
|
8
|
+
* Provides cookieName and fingerprintCookieName for cookie-based auth,
|
|
9
|
+
* and apiKey for API key auth fallback.
|
|
8
10
|
*/
|
|
9
11
|
space: any;
|
|
10
12
|
/**
|
|
11
|
-
* Authorization
|
|
13
|
+
* Authorization token extracted from the Authorization header upstream
|
|
14
|
+
* (e.g. already stripped of 'Bearer ' prefix in createContextDefault).
|
|
15
|
+
* Used as a fallback if no cookie or header token is found on req.
|
|
12
16
|
*/
|
|
13
17
|
authorization?: string;
|
|
18
|
+
/**
|
|
19
|
+
* Fingerprint value extracted upstream (e.g. from X-Fingerprint header).
|
|
20
|
+
* Used as a fallback if no fingerprint cookie or header is found on req.
|
|
21
|
+
*/
|
|
14
22
|
fingerprint?: string;
|
|
15
23
|
/**
|
|
16
|
-
*
|
|
24
|
+
* The original args object passed to the authenticating action.
|
|
25
|
+
* Available for subclasses that override extractCredentials() and need
|
|
26
|
+
* to derive credentials from action-specific parameters.
|
|
27
|
+
* Not used in the base implementation.
|
|
17
28
|
*/
|
|
18
29
|
params?: any;
|
|
19
30
|
}
|
|
@@ -1,7 +1,25 @@
|
|
|
1
1
|
import { PaginationAndSortingInterface } from '..';
|
|
2
2
|
export interface ListArgsInterface {
|
|
3
|
+
/**
|
|
4
|
+
* Filter params passed to onListFilter() in the gateway.
|
|
5
|
+
* Shape is resource-specific — each gateway interprets it in onListFilter().
|
|
6
|
+
*/
|
|
3
7
|
filter: any;
|
|
8
|
+
/**
|
|
9
|
+
* Pagination and sorting config (pageSize, page, sortBy).
|
|
10
|
+
* Converted to limit/offset/orderBy by db.createLimitOffsetSortBy().
|
|
11
|
+
*/
|
|
4
12
|
params?: PaginationAndSortingInterface;
|
|
13
|
+
/**
|
|
14
|
+
* When explicitly set, overrides config.noCache for this call.
|
|
15
|
+
* When true: fetches only ids, hydrates via the loader.
|
|
16
|
+
* When false: fetches selectFields directly, bypasses loader.
|
|
17
|
+
* Defaults to !config.noCache if not provided.
|
|
18
|
+
*/
|
|
5
19
|
useCache?: boolean;
|
|
20
|
+
/**
|
|
21
|
+
* Reserved for core-level callers. Not used by BaseGateway.list() —
|
|
22
|
+
* authentication is the core's responsibility, not the gateway's.
|
|
23
|
+
*/
|
|
6
24
|
skipAuth?: boolean;
|
|
7
25
|
}
|
|
@@ -1,7 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Interface for batch-loading data by key with per-request caching.
|
|
3
|
+
* Implemented by DataCache (DataLoader-backed) and any custom loaders
|
|
4
|
+
* passed via BaseGatewayPropsInterface.loader.
|
|
5
|
+
*
|
|
6
|
+
* Follows DataLoader semantics:
|
|
7
|
+
* - load() and loadMany() batch all calls within the same tick
|
|
8
|
+
* - Results are cached for the duration of the instance's lifetime
|
|
9
|
+
* - clear() and clearAll() invalidate cached entries
|
|
10
|
+
* - prime() seeds the cache without a round-trip
|
|
11
|
+
*/
|
|
1
12
|
export interface LoaderInterface {
|
|
13
|
+
/**
|
|
14
|
+
* Loads a single record by id. Batches concurrent calls within the
|
|
15
|
+
* same tick into a single underlying query.
|
|
16
|
+
* Returns null if the record is not found.
|
|
17
|
+
*/
|
|
2
18
|
load(id: any): Promise<any>;
|
|
3
|
-
|
|
19
|
+
/**
|
|
20
|
+
* Loads multiple records by their ids in a single batched call.
|
|
21
|
+
* Returns results in the same order as the input ids array,
|
|
22
|
+
* with null entries for any ids that were not found.
|
|
23
|
+
*/
|
|
24
|
+
loadMany(ids: any[]): Promise<any[]>;
|
|
25
|
+
/**
|
|
26
|
+
* Clears the cached value for one or more keys.
|
|
27
|
+
* Accepts either a single id or an array of ids.
|
|
28
|
+
* Returns `this` for chaining.
|
|
29
|
+
*/
|
|
4
30
|
clear(key: any | any[]): this;
|
|
31
|
+
/**
|
|
32
|
+
* Clears all cached values from this loader instance.
|
|
33
|
+
* Returns `this` for chaining.
|
|
34
|
+
*/
|
|
5
35
|
clearAll(): this;
|
|
36
|
+
/**
|
|
37
|
+
* Seeds the cache with a known value for the given key, avoiding
|
|
38
|
+
* a load() round-trip for recently written records.
|
|
39
|
+
* Returns `this` for chaining.
|
|
40
|
+
*/
|
|
6
41
|
prime(key: any, value: any): this;
|
|
7
42
|
}
|
|
@@ -1,8 +1,26 @@
|
|
|
1
1
|
export interface UserTokenParams {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
2
|
+
/**
|
|
3
|
+
* The user's ID — used as the JWT `subject` claim. Required.
|
|
4
|
+
*/
|
|
5
5
|
userId: string;
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
/**
|
|
7
|
+
* The space (tenant) ID the token is scoped to.
|
|
8
|
+
*/
|
|
9
|
+
spaceId?: string;
|
|
10
|
+
/**
|
|
11
|
+
* The account ID associated with the user.
|
|
12
|
+
*/
|
|
13
|
+
accountId?: string;
|
|
14
|
+
/**
|
|
15
|
+
* The role ID assigned to the user for this token.
|
|
16
|
+
*/
|
|
17
|
+
roleId?: string;
|
|
18
|
+
/**
|
|
19
|
+
* The language preference for this session.
|
|
20
|
+
*/
|
|
21
|
+
lang?: string;
|
|
22
|
+
/**
|
|
23
|
+
* Additional arbitrary string claims to include in the token payload.
|
|
24
|
+
*/
|
|
25
|
+
[tokenProp: string]: string | undefined;
|
|
8
26
|
}
|
|
@@ -1,13 +1,53 @@
|
|
|
1
1
|
export interface VerifyUserTokenArgs {
|
|
2
|
-
|
|
2
|
+
/**
|
|
3
|
+
* Accepted signing algorithms. Defaults to [defaultJwtAlgorithm] (HS256).
|
|
4
|
+
*/
|
|
5
|
+
algorithms?: string[];
|
|
6
|
+
/**
|
|
7
|
+
* Expected audience claim. Must match the `aud` in the token.
|
|
8
|
+
*/
|
|
3
9
|
audience?: string | string[];
|
|
10
|
+
/**
|
|
11
|
+
* Expected issuer claim. Must match the `iss` in the token.
|
|
12
|
+
* Accepts a single string or array of accepted issuers.
|
|
13
|
+
*/
|
|
4
14
|
issuer?: string | string[];
|
|
15
|
+
/**
|
|
16
|
+
* When true, expired tokens are accepted without error.
|
|
17
|
+
* Use only in specific scenarios (e.g. token refresh flows).
|
|
18
|
+
*/
|
|
5
19
|
ignoreExpiration?: boolean;
|
|
20
|
+
/**
|
|
21
|
+
* When true, ignores the `nbf` (not-before) claim.
|
|
22
|
+
*/
|
|
6
23
|
ignoreNotBefore?: boolean;
|
|
24
|
+
/**
|
|
25
|
+
* Expected subject claim. Must match the `sub` in the token.
|
|
26
|
+
*/
|
|
7
27
|
subject?: string;
|
|
28
|
+
/**
|
|
29
|
+
* Allowed clock skew in seconds when validating `exp` and `nbf` claims.
|
|
30
|
+
* Useful for systems with slight clock drift between services.
|
|
31
|
+
*/
|
|
8
32
|
clockTolerance?: number;
|
|
9
|
-
|
|
33
|
+
/**
|
|
34
|
+
* Maximum allowed token age as seconds or a string duration (e.g. '2h').
|
|
35
|
+
* Tokens older than this are rejected even if `exp` has not been reached.
|
|
36
|
+
*/
|
|
37
|
+
maxAge?: number | string;
|
|
38
|
+
/**
|
|
39
|
+
* Override the current timestamp (Unix seconds) used for claim validation.
|
|
40
|
+
* Useful in tests to simulate token verification at a specific point in time.
|
|
41
|
+
*/
|
|
10
42
|
clockTimestamp?: number;
|
|
43
|
+
/**
|
|
44
|
+
* Expected `nonce` claim for OpenID Connect ID tokens.
|
|
45
|
+
*/
|
|
11
46
|
nonce?: string;
|
|
47
|
+
/**
|
|
48
|
+
* Client-side fingerprint (from a secure cookie) to compare against the
|
|
49
|
+
* fingerprint embedded in the token payload.
|
|
50
|
+
* A mismatch results in UNAUTHORIZED — mitigates token theft.
|
|
51
|
+
*/
|
|
12
52
|
fingerprint?: string;
|
|
13
53
|
}
|
|
@@ -26,3 +26,7 @@ export * from './ExtractCredentialsArgs';
|
|
|
26
26
|
export * from './DownloadFileArgs';
|
|
27
27
|
export * from './BuildListQueryArgsInterface';
|
|
28
28
|
export * from './BaseCoreDoAuthOnActionInterface';
|
|
29
|
+
export * from './BaseControllerPropsInterface';
|
|
30
|
+
export * from './BaseRestApiCrudControllerPropsInterface';
|
|
31
|
+
export * from './BaseExternalApiGatewayPropsInterface';
|
|
32
|
+
export * from './DataCachePropsInterface';
|
|
@@ -25,3 +25,7 @@ export * from './ExtractCredentialsArgs';
|
|
|
25
25
|
export * from './DownloadFileArgs';
|
|
26
26
|
export * from './BuildListQueryArgsInterface';
|
|
27
27
|
export * from './BaseCoreDoAuthOnActionInterface';
|
|
28
|
+
export * from './BaseControllerPropsInterface';
|
|
29
|
+
export * from './BaseRestApiCrudControllerPropsInterface';
|
|
30
|
+
export * from './BaseExternalApiGatewayPropsInterface';
|
|
31
|
+
export * from './DataCachePropsInterface';
|
|
@@ -1 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Builds a Knex configuration object for the current environment.
|
|
3
|
+
*
|
|
4
|
+
* Reads connection and migration settings from `appConfig` (typically built
|
|
5
|
+
* by `buildConfig()`) and returns a fully configured Knex config object
|
|
6
|
+
* for the active `nodeEnv`. Falls back to the `development` config if
|
|
7
|
+
* `nodeEnv` does not match 'development' or 'production'.
|
|
8
|
+
*
|
|
9
|
+
* Built-in behaviours:
|
|
10
|
+
* - All query results are post-processed to camelCase via `camelResponse`
|
|
11
|
+
* - All identifiers are converted to snake_case via `wrapIdentifier`,
|
|
12
|
+
* with an optional override map for exceptions
|
|
13
|
+
* - Pool config can be provided as a full object (`dbPool`) or as
|
|
14
|
+
* individual min/max values (`dbPoolMin`, `dbPoolMax`)
|
|
15
|
+
* - Database port is coerced to a Number internally — no need to do this
|
|
16
|
+
* in the consuming app
|
|
17
|
+
* - MSSQL-specific connection options (encrypt, trustServerCertificate, etc.)
|
|
18
|
+
* are included automatically when `dbType === 'mssql'`
|
|
19
|
+
* - PostgreSQL searchPath is set automatically when `dbType === 'pg'`
|
|
20
|
+
* and `dbSchema` is provided
|
|
21
|
+
*
|
|
22
|
+
* @param dirName Absolute path to the directory containing migrations/seeds.
|
|
23
|
+
* Pass `__dirname` or `import.meta.dirname` from your entry point.
|
|
24
|
+
* @param appConfig Flat config object, typically from `buildConfig()`.
|
|
25
|
+
*/
|
|
1
26
|
export declare const buildKnexConfig: (dirName: string, appConfig: any) => any;
|
|
@@ -1,42 +1,82 @@
|
|
|
1
|
+
// ./src/knexConfigBuilder.ts
|
|
1
2
|
import path from 'path';
|
|
2
|
-
import { snakeCase
|
|
3
|
+
import { snakeCase } from 'lodash';
|
|
3
4
|
import { camelKeys } from '@sdflc/utils';
|
|
4
5
|
const defaultMigrationsTable = 'migrations';
|
|
5
6
|
const defaultMigrationsFolder = 'migrations';
|
|
6
7
|
const defaultMigrationsTemplateFileName = 'migrations-template.js';
|
|
7
8
|
const defaultSeedsFolder = 'seeds';
|
|
9
|
+
/**
|
|
10
|
+
* Post-processes Knex query results by converting all keys to camelCase.
|
|
11
|
+
*
|
|
12
|
+
* Knex calls this with the already-processed result which is either:
|
|
13
|
+
* - An array of row objects (SELECT queries)
|
|
14
|
+
* - A non-array object (INSERT/UPDATE with RETURNING, aggregate queries, etc.)
|
|
15
|
+
*
|
|
16
|
+
* The `result.rows` guard handles edge cases where a raw pg-driver result
|
|
17
|
+
* shape leaks through — in that case we return it unchanged since Knex's
|
|
18
|
+
* own processing has not yet run.
|
|
19
|
+
*
|
|
20
|
+
* See: https://knexjs.org/guide/#post-process-response
|
|
21
|
+
*/
|
|
8
22
|
const camelResponse = (result) => {
|
|
9
23
|
if (!result || result.rows) {
|
|
10
24
|
return result;
|
|
11
25
|
}
|
|
12
26
|
return camelKeys(result);
|
|
13
27
|
};
|
|
28
|
+
/**
|
|
29
|
+
* Builds a Knex configuration object for the current environment.
|
|
30
|
+
*
|
|
31
|
+
* Reads connection and migration settings from `appConfig` (typically built
|
|
32
|
+
* by `buildConfig()`) and returns a fully configured Knex config object
|
|
33
|
+
* for the active `nodeEnv`. Falls back to the `development` config if
|
|
34
|
+
* `nodeEnv` does not match 'development' or 'production'.
|
|
35
|
+
*
|
|
36
|
+
* Built-in behaviours:
|
|
37
|
+
* - All query results are post-processed to camelCase via `camelResponse`
|
|
38
|
+
* - All identifiers are converted to snake_case via `wrapIdentifier`,
|
|
39
|
+
* with an optional override map for exceptions
|
|
40
|
+
* - Pool config can be provided as a full object (`dbPool`) or as
|
|
41
|
+
* individual min/max values (`dbPoolMin`, `dbPoolMax`)
|
|
42
|
+
* - Database port is coerced to a Number internally — no need to do this
|
|
43
|
+
* in the consuming app
|
|
44
|
+
* - MSSQL-specific connection options (encrypt, trustServerCertificate, etc.)
|
|
45
|
+
* are included automatically when `dbType === 'mssql'`
|
|
46
|
+
* - PostgreSQL searchPath is set automatically when `dbType === 'pg'`
|
|
47
|
+
* and `dbSchema` is provided
|
|
48
|
+
*
|
|
49
|
+
* @param dirName Absolute path to the directory containing migrations/seeds.
|
|
50
|
+
* Pass `__dirname` or `import.meta.dirname` from your entry point.
|
|
51
|
+
* @param appConfig Flat config object, typically from `buildConfig()`.
|
|
52
|
+
*/
|
|
14
53
|
export const buildKnexConfig = (dirName, appConfig) => {
|
|
15
54
|
const { dbType, dbHost, dbPort, dbName, dbSchema, dbUser, dbPassword, dbPoolMin, dbPoolMax, debug, nodeEnv, migrationsTemplateFileName, migrationsFolder, migrationsTable, useSchemaForMigrationsTable, seedsFolder, seedsFolderDev, seedsFolderProd, wrapIdentifierOverrideMap, dbPool, } = appConfig;
|
|
16
|
-
const
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
connection: {
|
|
27
|
-
host: dbHost,
|
|
28
|
-
port: dbPort,
|
|
29
|
-
user: dbUser,
|
|
30
|
-
password: dbPassword,
|
|
31
|
-
database: dbName,
|
|
32
|
-
//ssl: database.ssl,
|
|
33
|
-
},
|
|
55
|
+
const resolvedDbType = dbType || 'pg';
|
|
56
|
+
// ─── Connection ──────────────────────────────────────────────────────────
|
|
57
|
+
const connection = {
|
|
58
|
+
host: dbHost,
|
|
59
|
+
// Fix: coerce port to Number here so consuming apps don't need to do it
|
|
60
|
+
port: dbPort != null ? Number(dbPort) : undefined,
|
|
61
|
+
user: dbUser,
|
|
62
|
+
password: dbPassword,
|
|
63
|
+
database: dbName,
|
|
64
|
+
connectionTimeout: 30000,
|
|
34
65
|
};
|
|
35
|
-
|
|
36
|
-
|
|
66
|
+
// MSSQL-specific connection options — previously repeated in every project
|
|
67
|
+
if (resolvedDbType === 'mssql') {
|
|
68
|
+
connection.options = {
|
|
69
|
+
encrypt: true,
|
|
70
|
+
trustServerCertificate: false,
|
|
71
|
+
enableArithAbort: true,
|
|
72
|
+
requestTimeout: 30000,
|
|
73
|
+
connectionTimeout: 30000,
|
|
74
|
+
};
|
|
37
75
|
}
|
|
38
|
-
|
|
39
|
-
|
|
76
|
+
// ─── Pool ─────────────────────────────────────────────────────────────────
|
|
77
|
+
const pool = typeof dbPool === 'object'
|
|
78
|
+
? dbPool
|
|
79
|
+
: {
|
|
40
80
|
min: dbPoolMin != null && !isNaN(dbPoolMin) ? dbPoolMin : 0,
|
|
41
81
|
max: dbPoolMax != null && !isNaN(dbPoolMax) ? dbPoolMax : 50,
|
|
42
82
|
acquireTimeoutMillis: 30000,
|
|
@@ -47,17 +87,45 @@ export const buildKnexConfig = (dirName, appConfig) => {
|
|
|
47
87
|
createRetryIntervalMillis: 200,
|
|
48
88
|
propagateCreateError: false,
|
|
49
89
|
};
|
|
90
|
+
// ─── Shared config ────────────────────────────────────────────────────────
|
|
91
|
+
const sharedConfig = {
|
|
92
|
+
client: resolvedDbType,
|
|
93
|
+
postProcessResponse: camelResponse,
|
|
94
|
+
/**
|
|
95
|
+
* Converts camelCase JS identifiers to snake_case DB column names.
|
|
96
|
+
* '*' is passed through unchanged (Knex uses it for SELECT *).
|
|
97
|
+
* `wrapIdentifierOverrideMap` allows exceptions for identifiers that
|
|
98
|
+
* should not be snake_cased (e.g. already-snake_cased names, reserved words).
|
|
99
|
+
*/
|
|
100
|
+
wrapIdentifier: (value, origImpl) => {
|
|
101
|
+
if (value === '*') {
|
|
102
|
+
return origImpl(value);
|
|
103
|
+
}
|
|
104
|
+
return wrapIdentifierOverrideMap?.[value] || origImpl(snakeCase(value));
|
|
105
|
+
},
|
|
106
|
+
connection,
|
|
107
|
+
pool,
|
|
108
|
+
};
|
|
109
|
+
// pg searchPath — previously set in every project after buildKnexConfig()
|
|
110
|
+
if (resolvedDbType === 'pg' && dbSchema) {
|
|
111
|
+
sharedConfig.searchPath = [dbSchema, 'public'];
|
|
50
112
|
}
|
|
113
|
+
// ─── Migration config ─────────────────────────────────────────────────────
|
|
114
|
+
const migrationsConfig = {
|
|
115
|
+
directory: path.join(dirName, migrationsFolder || defaultMigrationsFolder),
|
|
116
|
+
schemaName: useSchemaForMigrationsTable ? dbSchema : undefined,
|
|
117
|
+
tableName: migrationsTable || defaultMigrationsTable,
|
|
118
|
+
};
|
|
119
|
+
// ─── Environment configs ──────────────────────────────────────────────────
|
|
51
120
|
const config = {
|
|
52
121
|
development: {
|
|
53
122
|
...sharedConfig,
|
|
123
|
+
// debug defaults to false in production even if env var is set
|
|
54
124
|
debug,
|
|
55
125
|
migrations: {
|
|
56
|
-
//
|
|
126
|
+
// stub is only needed in development (used by `knex migrate:make`)
|
|
57
127
|
stub: path.join(dirName, migrationsTemplateFileName || defaultMigrationsTemplateFileName),
|
|
58
|
-
|
|
59
|
-
schemaName: useSchemaForMigrationsTable ? dbSchema : undefined,
|
|
60
|
-
tableName: migrationsTable || defaultMigrationsTable,
|
|
128
|
+
...migrationsConfig,
|
|
61
129
|
},
|
|
62
130
|
seeds: {
|
|
63
131
|
directory: path.join(dirName, seedsFolderDev || seedsFolder || defaultSeedsFolder),
|
|
@@ -65,20 +133,16 @@ export const buildKnexConfig = (dirName, appConfig) => {
|
|
|
65
133
|
},
|
|
66
134
|
production: {
|
|
67
135
|
...sharedConfig,
|
|
68
|
-
debug,
|
|
136
|
+
debug: false, // never enable debug in production regardless of env var
|
|
69
137
|
migrations: {
|
|
70
|
-
|
|
71
|
-
schemaName: useSchemaForMigrationsTable ? dbSchema : undefined,
|
|
72
|
-
tableName: migrationsTable || defaultMigrationsTable,
|
|
138
|
+
...migrationsConfig,
|
|
73
139
|
},
|
|
74
140
|
seeds: {
|
|
75
141
|
directory: path.join(dirName, seedsFolderProd || seedsFolder || defaultSeedsFolder),
|
|
76
142
|
},
|
|
77
143
|
},
|
|
78
144
|
};
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
}
|
|
83
|
-
return config2use;
|
|
145
|
+
// Fix: direct bracket access instead of lodash get() — avoids dot-notation
|
|
146
|
+
// path interpretation (e.g. 'development.migrations' would be misread)
|
|
147
|
+
return config[nodeEnv] ?? config.development;
|
|
84
148
|
};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parses a raw :id route param into a single string or an array of strings.
|
|
3
|
+
* If the value contains commas, it is split, trimmed, and empty entries removed.
|
|
4
|
+
* Returns a tuple so callers can branch cleanly without re-checking.
|
|
5
|
+
*/
|
|
6
|
+
export declare const parseIds: (raw: string) => [isSingle: boolean, ids: string[]];
|