@sdflc/backend-helpers 1.0.111 → 1.0.113
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 +470 -33
- package/build/BaseCore.js +613 -126
- 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/RedisDataLoader.d.ts +144 -21
- package/build/RedisDataLoader.js +178 -49
- package/build/apiContext.d.ts +0 -8
- package/build/apiContext.js +12 -27
- 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 +470 -33
- package/build/esm/BaseCore.js +615 -128
- 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/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 +12 -27
- 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 +5 -2
- package/build/esm/index.js +5 -2
- package/build/esm/interfaces/ApiContext.d.ts +7 -3
- 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 +87 -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 +20 -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 -0
- package/build/esm/utils.js +23 -1
- package/build/index.d.ts +5 -2
- package/build/index.js +5 -2
- package/build/interfaces/ApiContext.d.ts +7 -3
- 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 +87 -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 +20 -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 -0
- package/build/utils.js +23 -1
- package/package.json +19 -18
- package/build/baseController.d.ts +0 -17
- package/build/baseController.js +0 -63
- 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 -57
- package/build/esm/configBulder.d.ts +0 -2
- package/build/esm/configBulder.js +0 -32
|
@@ -4,12 +4,33 @@ import { CacheInterface } from '..';
|
|
|
4
4
|
import { LoaderInterface } from './LoaderInterface';
|
|
5
5
|
import { SortItemInterface } from './SortItemInterface';
|
|
6
6
|
export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
7
|
+
/**
|
|
8
|
+
* The full request-scoped ApiContext. Required — gateways use it to
|
|
9
|
+
* access userId, spaceId, requestId, other gateways, and usedKeyPrefixes.
|
|
10
|
+
*/
|
|
7
11
|
context: ApiContext;
|
|
8
12
|
table?: string;
|
|
13
|
+
/**
|
|
14
|
+
* Primary key field name used for SELECT and loader operations.
|
|
15
|
+
* Defaults to the global ID_FIELD constant.
|
|
16
|
+
*/
|
|
9
17
|
idField?: string;
|
|
18
|
+
/**
|
|
19
|
+
* Field name used in UPDATE/DELETE WHERE clauses.
|
|
20
|
+
* Separate from idField for tables where the write target differs
|
|
21
|
+
* from the read key. Defaults to idField → ID_FIELD.
|
|
22
|
+
*/
|
|
10
23
|
idFieldUpdateRemove?: string;
|
|
11
24
|
idFieldAs?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Conflict target field(s) for the set() upsert operation.
|
|
27
|
+
* Passed to .onConflict(). Defaults to idFieldUpdateRemove.
|
|
28
|
+
*/
|
|
12
29
|
setFields?: string[] | string;
|
|
30
|
+
/**
|
|
31
|
+
* Explicit list of fields to include in the ON CONFLICT MERGE clause.
|
|
32
|
+
* If not set, all keys across all objects are used (minus skipFields).
|
|
33
|
+
*/
|
|
13
34
|
mergeFields?: string[];
|
|
14
35
|
hasStatus?: boolean;
|
|
15
36
|
hasCreatedBy?: boolean;
|
|
@@ -17,23 +38,77 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
17
38
|
hasRemovedBy?: boolean;
|
|
18
39
|
hasCreatedAt?: boolean;
|
|
19
40
|
hasUpdatedAt?: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* Enables soft-delete behaviour. When true, remove() issues an UPDATE
|
|
43
|
+
* with removedAt set instead of a DELETE.
|
|
44
|
+
*/
|
|
20
45
|
hasRemovedAt?: boolean;
|
|
46
|
+
/**
|
|
47
|
+
* When true, also writes a formatted string timestamp to removedAtStr.
|
|
48
|
+
* Useful for building composite keys that encode the removal time.
|
|
49
|
+
*/
|
|
21
50
|
hasRemovedAtStr?: boolean;
|
|
51
|
+
/**
|
|
52
|
+
* When true, scopes reads and writes to the current spaceId from context.
|
|
53
|
+
*/
|
|
22
54
|
hasSpace?: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Enables optimistic locking via a version field.
|
|
57
|
+
* update() checks version in the WHERE clause and increments it on success.
|
|
58
|
+
*/
|
|
23
59
|
hasVersion?: boolean;
|
|
24
60
|
hasLang?: boolean;
|
|
25
61
|
hasUserId?: boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Field name used to build a composite id for localised records.
|
|
64
|
+
* Combined with the lang field: buildKey([params[localizationForField], params.lang]).
|
|
65
|
+
*/
|
|
26
66
|
localizationForField?: string;
|
|
27
67
|
defaultSorting?: SortItemInterface[];
|
|
68
|
+
/**
|
|
69
|
+
* Field to apply keyword (ILIKE) search against when filterParams.keyword is set.
|
|
70
|
+
*/
|
|
28
71
|
fieldForKeyword?: string;
|
|
72
|
+
/**
|
|
73
|
+
* Field name to scope list queries to the current userId from context.
|
|
74
|
+
* e.g. 'userId' → WHERE userId = context.userId
|
|
75
|
+
*/
|
|
29
76
|
filterByUserField?: string;
|
|
77
|
+
/**
|
|
78
|
+
* Number of records per INSERT batch. Defaults to 2500.
|
|
79
|
+
* Prevents hitting DB parameter limits on large inserts.
|
|
80
|
+
*/
|
|
30
81
|
insertChunkSize?: number;
|
|
82
|
+
/**
|
|
83
|
+
* When true, remove() issues a hard DELETE regardless of hasRemovedAt.
|
|
84
|
+
*/
|
|
31
85
|
hardRemove?: boolean;
|
|
86
|
+
/**
|
|
87
|
+
* Custom loader implementing LoaderInterface (load + loadMany).
|
|
88
|
+
* Defaults to DataCache (DataLoader-backed in-memory cache).
|
|
89
|
+
*/
|
|
32
90
|
loader?: LoaderInterface;
|
|
91
|
+
/**
|
|
92
|
+
* When true, bypasses the loader cache and fetches directly from the DB.
|
|
93
|
+
*/
|
|
33
94
|
noCache?: boolean;
|
|
95
|
+
/**
|
|
96
|
+
* Columns to include in RETURNING clauses. Defaults to ['*'].
|
|
97
|
+
*/
|
|
34
98
|
returnFields?: any[];
|
|
99
|
+
/**
|
|
100
|
+
* Status values considered "active" for list filtering.
|
|
101
|
+
* Used when no explicit status filter is provided. Defaults to [STATUSES.ACTIVE].
|
|
102
|
+
*/
|
|
35
103
|
activeStatuses?: number[];
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
104
|
+
/**
|
|
105
|
+
* Optional — falls back to a new Logger({ level: WARNING }) if not provided
|
|
106
|
+
* or if the value fails the isLogger() duck-type check.
|
|
107
|
+
*/
|
|
108
|
+
logger?: Logger;
|
|
109
|
+
/**
|
|
110
|
+
* Optional — available to subclasses that need to vary behaviour
|
|
111
|
+
* between production and non-production environments.
|
|
112
|
+
*/
|
|
113
|
+
isProduction?: boolean;
|
|
39
114
|
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export interface BaseRestApiCrudControllerPropsInterface {
|
|
2
|
+
/**
|
|
3
|
+
* The prefix used to derive the core name, e.g. "user" → "userCore".
|
|
4
|
+
* Ignored if `core` is provided explicitly.
|
|
5
|
+
*/
|
|
6
|
+
prefix?: string;
|
|
7
|
+
/**
|
|
8
|
+
* Explicit core name in context.cores to use.
|
|
9
|
+
* Defaults to `${prefix}Core`.
|
|
10
|
+
*/
|
|
11
|
+
core?: string;
|
|
12
|
+
/**
|
|
13
|
+
* Factory that produces the ApiContext for a given request.
|
|
14
|
+
* Required — controllers need context to reach cores.
|
|
15
|
+
*/
|
|
16
|
+
getContext: (req: any) => Promise<any> | any;
|
|
17
|
+
onResponse?: (req: any, res: any, next: any) => Promise<void> | void;
|
|
18
|
+
logger?: any;
|
|
19
|
+
disableList?: boolean;
|
|
20
|
+
disableGet?: boolean;
|
|
21
|
+
disableGetMany?: boolean;
|
|
22
|
+
disableCreate?: boolean;
|
|
23
|
+
disableCreateMany?: boolean;
|
|
24
|
+
disableUpdate?: boolean;
|
|
25
|
+
disableUpdateMany?: boolean;
|
|
26
|
+
disableRemove?: boolean;
|
|
27
|
+
disableRemoveMany?: boolean;
|
|
28
|
+
}
|
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
export interface BuildConfigOptions {
|
|
2
|
+
/**
|
|
3
|
+
* Path to the .env file, relative to the `dirName` passed to `buildConfig()`.
|
|
4
|
+
* Defaults to '.env'.
|
|
5
|
+
*/
|
|
2
6
|
envFile?: string;
|
|
7
|
+
/**
|
|
8
|
+
* Path to the .env example/template file, relative to `dirName`.
|
|
9
|
+
* Used by dotenv-safe to verify all required variables are present.
|
|
10
|
+
* Defaults to '.env.example'.
|
|
11
|
+
*/
|
|
3
12
|
envFileExample?: string;
|
|
13
|
+
/**
|
|
14
|
+
* Value to use for NODE_ENV if it is not set in the environment.
|
|
15
|
+
* Defaults to 'development'.
|
|
16
|
+
*/
|
|
4
17
|
defaultNodeEnv?: string;
|
|
18
|
+
/**
|
|
19
|
+
* When true, dotenv-safe will not throw if variables declared in the
|
|
20
|
+
* example file are present but have empty values in the .env file.
|
|
21
|
+
* Defaults to true.
|
|
22
|
+
*/
|
|
5
23
|
allowEmptyValues?: boolean;
|
|
6
24
|
}
|
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
export interface BuildListQueryArgsInterface {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
2
|
+
/**
|
|
3
|
+
* Filter params passed to onListFilter().
|
|
4
|
+
* Optional — buildListQuery() itself does not apply filters;
|
|
5
|
+
* it only selects fields. onListFilter() receives filter separately.
|
|
6
|
+
*/
|
|
7
|
+
filter?: any;
|
|
8
|
+
/**
|
|
9
|
+
* Pagination and sorting params (limit, offset, sortBy).
|
|
10
|
+
* Optional — subclasses that build joins or computed columns
|
|
11
|
+
* may need params to scope the query.
|
|
12
|
+
*/
|
|
13
|
+
params?: any;
|
|
14
|
+
/**
|
|
15
|
+
* Columns to SELECT. When useCache is true this will be just the id field;
|
|
16
|
+
* when false it will be selectFields from config or '*'.
|
|
17
|
+
*/
|
|
18
|
+
fieldsToUse?: any;
|
|
19
|
+
/**
|
|
20
|
+
* Whether the list result will be hydrated through the loader cache.
|
|
21
|
+
* Passed so subclasses can adjust query shape based on cache strategy.
|
|
22
|
+
*/
|
|
23
|
+
useCache?: boolean;
|
|
6
24
|
}
|
|
@@ -1,12 +1,29 @@
|
|
|
1
1
|
import { Database } from '../Database';
|
|
2
2
|
export interface CacheInterface {
|
|
3
3
|
db: Database;
|
|
4
|
+
/**
|
|
5
|
+
* Namespace prefix for DataLoader cache keys.
|
|
6
|
+
* Resolved in BaseGateway as: context.keyPrefix → config.keyPrefix → table name.
|
|
7
|
+
* Uniqueness within a request is enforced by usedKeyPrefixes on ApiContext.
|
|
8
|
+
*/
|
|
4
9
|
keyPrefix?: string;
|
|
5
|
-
|
|
10
|
+
/**
|
|
11
|
+
* Note: context is intentionally omitted here — it is declared as
|
|
12
|
+
* `context: ApiContext` (required, strongly typed) on BaseGatewayPropsInterface
|
|
13
|
+
* which extends this interface. Declaring it here as `any` would conflict
|
|
14
|
+
* with the stronger type and cause ambiguity.
|
|
15
|
+
*/
|
|
6
16
|
table?: string;
|
|
7
17
|
idField?: string;
|
|
8
18
|
idFieldAs?: string;
|
|
19
|
+
/**
|
|
20
|
+
* Columns fetched when useCache is false in list().
|
|
21
|
+
* Defaults to '*' if not set.
|
|
22
|
+
*/
|
|
9
23
|
selectFields?: any[];
|
|
24
|
+
/**
|
|
25
|
+
* When true, the loader pre-fetches all records on first access.
|
|
26
|
+
*/
|
|
10
27
|
readAll?: boolean;
|
|
11
28
|
redisClient?: any;
|
|
12
29
|
cacheTtl?: number;
|
|
@@ -3,6 +3,22 @@ export interface CoreActionInterface {
|
|
|
3
3
|
args: any;
|
|
4
4
|
actionName?: string;
|
|
5
5
|
doAuth?: boolean;
|
|
6
|
+
/**
|
|
7
|
+
* When true, attempts authentication but does not fail if it does not succeed.
|
|
8
|
+
* If a valid JWT is present, context will be populated with accountId, userId,
|
|
9
|
+
* roleId, etc. as normal. If no token is present or verification fails, the
|
|
10
|
+
* request continues unauthenticated with no error returned.
|
|
11
|
+
*
|
|
12
|
+
* Use for public endpoints that behave differently for authenticated users
|
|
13
|
+
* (e.g. personalised content, showing ownership state, soft-gating features).
|
|
14
|
+
*
|
|
15
|
+
* Runs before `requireSpace` — if soft auth populates the context, space
|
|
16
|
+
* verification will have the enriched context available.
|
|
17
|
+
*
|
|
18
|
+
* Mutually exclusive intent with `doAuth` — if `doAuth` is true, this flag
|
|
19
|
+
* is ignored since a hard auth failure is already enforced.
|
|
20
|
+
*/
|
|
21
|
+
tryAuth?: boolean;
|
|
6
22
|
accessRights?: any[];
|
|
7
23
|
roles?: string[];
|
|
8
24
|
validate?(args: any, opt: BaseCoreActionsInterface): Promise<any[]> | any[];
|
|
@@ -12,5 +28,9 @@ export interface CoreActionInterface {
|
|
|
12
28
|
onException?(params: any, opt?: BaseCoreActionsInterface): Promise<any | undefined | null>;
|
|
13
29
|
shouldLogArgs?: boolean;
|
|
14
30
|
requireSpace?: boolean;
|
|
31
|
+
/**
|
|
32
|
+
* When true, lets runAction skip the action result check that decides
|
|
33
|
+
* whether to commit or rollback the DB transaction.
|
|
34
|
+
*/
|
|
15
35
|
skipCheckResult?: boolean;
|
|
16
36
|
}
|
|
@@ -1,11 +1,45 @@
|
|
|
1
1
|
export interface CreateUserTokenArgs {
|
|
2
|
-
|
|
2
|
+
/**
|
|
3
|
+
* JWT signing algorithm. Defaults to the module-level defaultJwtAlgorithm
|
|
4
|
+
* (HS256 unless overridden via setDefaultJwtAlgorithm()).
|
|
5
|
+
*/
|
|
6
|
+
algorithm?: string;
|
|
7
|
+
/**
|
|
8
|
+
* JWT audience claim. Verified during token validation.
|
|
9
|
+
* Accepts a single string or array of strings.
|
|
10
|
+
*/
|
|
3
11
|
audience?: string | string[];
|
|
12
|
+
/**
|
|
13
|
+
* JWT issuer claim. Defaults to the module-level defaultIssuer.
|
|
14
|
+
*/
|
|
4
15
|
issuer?: string;
|
|
16
|
+
/**
|
|
17
|
+
* JWT ID claim. Defaults to a generated UUID v4 if not provided.
|
|
18
|
+
*/
|
|
5
19
|
jwtid?: string;
|
|
20
|
+
/**
|
|
21
|
+
* When true, omits the `iat` (issued-at) claim from the token.
|
|
22
|
+
* Defaults to false.
|
|
23
|
+
*/
|
|
6
24
|
noTimestamp?: boolean;
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
25
|
+
/**
|
|
26
|
+
* Additional JWT header fields to include.
|
|
27
|
+
*/
|
|
28
|
+
header?: Record<string, any>;
|
|
29
|
+
/**
|
|
30
|
+
* JWT `kid` (key ID) header parameter.
|
|
31
|
+
* Used to identify which key was used to sign the token.
|
|
32
|
+
*/
|
|
33
|
+
keyid?: string;
|
|
34
|
+
/**
|
|
35
|
+
* Token expiry as a number of seconds or a string duration (e.g. '2h', '7d').
|
|
36
|
+
* If not provided, the token does not expire.
|
|
37
|
+
*/
|
|
38
|
+
expiresIn?: number | string;
|
|
39
|
+
/**
|
|
40
|
+
* When true, generates a UUID fingerprint and embeds it in the token payload.
|
|
41
|
+
* The fingerprint should be stored in a secure cookie and passed to
|
|
42
|
+
* verifyUserToken() to mitigate token theft.
|
|
43
|
+
*/
|
|
10
44
|
useFingerprint?: boolean;
|
|
11
45
|
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { CacheInterface } from './CacheInterface';
|
|
2
|
+
/**
|
|
3
|
+
* Props for DataCache. Extends CacheInterface with request-scoped context,
|
|
4
|
+
* which is used to resolve the keyPrefix and passed through to custom
|
|
5
|
+
* loaderFn implementations.
|
|
6
|
+
*
|
|
7
|
+
* Kept separate from CacheInterface so that CacheInterface itself remains
|
|
8
|
+
* a clean, context-free storage config — usable without a request context.
|
|
9
|
+
* BaseGatewayPropsInterface declares context as ApiContext (strongly typed)
|
|
10
|
+
* separately.
|
|
11
|
+
*/
|
|
12
|
+
export interface DataCachePropsInterface extends CacheInterface {
|
|
13
|
+
/**
|
|
14
|
+
* Optional request-scoped context. Used to read context.keyPrefix for
|
|
15
|
+
* DataLoader cache key namespacing, and passed through to custom loaderFn
|
|
16
|
+
* implementations that may need request-level data (userId, spaceId, etc.).
|
|
17
|
+
* Typed as `any` since DataCache is a lower-level class that should not
|
|
18
|
+
* depend on ApiContext directly.
|
|
19
|
+
*/
|
|
20
|
+
context?: any;
|
|
21
|
+
}
|
|
@@ -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
|
}
|