@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,37 +1,174 @@
|
|
|
1
1
|
import { Logger } from '@sdflc/utils';
|
|
2
2
|
import { Database } from '../Database';
|
|
3
|
-
import { BaseGateway } from '../BaseGateway';
|
|
4
3
|
import { BaseCoreValidatorsInterface } from './BaseCoreValidatorsInterface';
|
|
5
4
|
import { BaseCoreDoingWhatInterface } from './BaseCoreDoingWhatInterface';
|
|
6
5
|
import { VerifyUserTokenArgs } from './VerifyUserTokenArgs';
|
|
7
6
|
import { ApiContext } from './ApiContext';
|
|
8
7
|
import { ID_TYPES } from '../constants';
|
|
9
8
|
import { BaseCoreDoAuthOnActionInterface } from './BaseCoreDoAuthOnActionInterface';
|
|
9
|
+
import { RateLimiterInterface, RateLimitRule } from '../IpRateLimiter';
|
|
10
|
+
/**
|
|
11
|
+
* Per-action rate-limit overrides. Each key maps to either:
|
|
12
|
+
* - A RateLimitRule object — use this rule for the action
|
|
13
|
+
* - false — explicitly disable rate limiting for the action
|
|
14
|
+
* even if a core-level default rule is configured
|
|
15
|
+
*
|
|
16
|
+
* Actions not listed here fall back to the core-level `rateLimit` default.
|
|
17
|
+
*/
|
|
18
|
+
export type BaseCoreRateLimitOnActionInterface = Partial<Record<'list' | 'get' | 'getMany' | 'create' | 'createMany' | 'update' | 'updateMany' | 'set' | 'remove' | 'removeMany', RateLimitRule | false>>;
|
|
10
19
|
export interface BaseCorePropsInterface {
|
|
11
20
|
/**
|
|
12
|
-
*
|
|
21
|
+
* Full request-scoped ApiContext. Required — cores use it to access
|
|
22
|
+
* userId, spaceId, gateways, requestId, headers, etc.
|
|
13
23
|
*/
|
|
14
24
|
context: ApiContext;
|
|
15
25
|
/**
|
|
16
|
-
* Database instance
|
|
26
|
+
* Database instance for transaction management and raw query access.
|
|
27
|
+
* Required — used by runAction() for startTransaction, commit, rollback,
|
|
28
|
+
* and by exceptionFailure() for isDbError() checks.
|
|
17
29
|
*/
|
|
18
30
|
db: Database;
|
|
19
31
|
/**
|
|
20
|
-
* Name of
|
|
32
|
+
* Name of the default gateway in context.gateways used for CRUD operations.
|
|
33
|
+
* Optional — some cores orchestrate other cores or always specify the
|
|
34
|
+
* gateway name explicitly via getGateway(name).
|
|
35
|
+
*/
|
|
36
|
+
gatewayName?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Optional — available to subclasses that vary behaviour between
|
|
39
|
+
* production and non-production environments (e.g. verbose error messages).
|
|
40
|
+
*/
|
|
41
|
+
isProduction?: boolean;
|
|
42
|
+
/**
|
|
43
|
+
* Optional — falls back to a module-level Logger({ level: ERROR }) if not
|
|
44
|
+
* provided or if the value fails the isLogger() duck-type check.
|
|
45
|
+
* Duck-typed to avoid instanceof failures across package versions.
|
|
46
|
+
*/
|
|
47
|
+
logger?: Logger;
|
|
48
|
+
/**
|
|
49
|
+
* Human-readable name for this core. Used as the default `doingWhat`
|
|
50
|
+
* string in log messages and error reports when doingWhat is not set.
|
|
21
51
|
*/
|
|
22
|
-
gatewayName: string;
|
|
23
|
-
isProduction: boolean;
|
|
24
|
-
logger: Logger;
|
|
25
52
|
name?: string;
|
|
26
|
-
|
|
53
|
+
/**
|
|
54
|
+
* Master auth switch. When true, all actions require authentication
|
|
55
|
+
* unless overridden per-action via doAuthOnAction.
|
|
56
|
+
* Optional — defaults to false (no auth required).
|
|
57
|
+
*/
|
|
58
|
+
doAuth?: boolean;
|
|
59
|
+
/**
|
|
60
|
+
* Per-action auth overrides. Each action independently enables or disables
|
|
61
|
+
* auth. Falls back to doAuth if not set for a specific action.
|
|
62
|
+
*
|
|
63
|
+
* Example — require auth globally but allow public list:
|
|
64
|
+
* { doAuth: true, doAuthOnAction: { list: false } }
|
|
65
|
+
*/
|
|
27
66
|
doAuthOnAction?: BaseCoreDoAuthOnActionInterface;
|
|
67
|
+
/**
|
|
68
|
+
* Custom doingWhat strings for log messages per action.
|
|
69
|
+
* e.g. { create: 'creating a user account', remove: 'deleting a user' }
|
|
70
|
+
* Falls back to `name` then to a built-in default string if not set.
|
|
71
|
+
*/
|
|
28
72
|
doingWhat?: BaseCoreDoingWhatInterface;
|
|
73
|
+
/**
|
|
74
|
+
* Custom validator map. If not provided, getValidators() returns the
|
|
75
|
+
* default validators (validateGet, validateGetMany, validateRemove,
|
|
76
|
+
* validateRemoveMany, and no-op defaults for mutations).
|
|
77
|
+
*/
|
|
29
78
|
validators?: BaseCoreValidatorsInterface;
|
|
30
|
-
|
|
79
|
+
/**
|
|
80
|
+
* Gateway used to resolve the current space by spaceId.
|
|
81
|
+
* Typed structurally rather than as BaseGateway to avoid instanceof
|
|
82
|
+
* coupling across package versions — any object with a get() method works.
|
|
83
|
+
*
|
|
84
|
+
* Used by findSpace() to look up space config (tokenSecret, apiKey, etc.)
|
|
85
|
+
* when context.space is not already populated.
|
|
86
|
+
*/
|
|
87
|
+
spaceGw?: {
|
|
88
|
+
get(id: string): Promise<any>;
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* Shared secret for service-to-service API calls.
|
|
92
|
+
* When context.apiKey matches this value, authentication is bypassed
|
|
93
|
+
* and the request is treated as a trusted interservice call.
|
|
94
|
+
*/
|
|
31
95
|
interserviceApiKey?: string;
|
|
96
|
+
/**
|
|
97
|
+
* JWT secret used to verify user tokens.
|
|
98
|
+
* Can be overridden per-space via getJwtTokenSecretAndSettings().
|
|
99
|
+
*/
|
|
32
100
|
jwtSecret?: string;
|
|
101
|
+
/**
|
|
102
|
+
* Additional options passed to the JWT verification function.
|
|
103
|
+
* e.g. algorithms, audience, issuer, clockTolerance.
|
|
104
|
+
* Merged with defaults in getJwtTokenSecretAndSettings().
|
|
105
|
+
*/
|
|
33
106
|
verifyTokenArgs?: VerifyUserTokenArgs;
|
|
107
|
+
/**
|
|
108
|
+
* When true, create() automatically calculates and sets the orderNo
|
|
109
|
+
* field before inserting. Uses getFilterToSetOrderNo() to scope the
|
|
110
|
+
* sequence and getGatewayToSetOrerNo() to query the current max.
|
|
111
|
+
*/
|
|
34
112
|
hasOrderNo?: boolean;
|
|
113
|
+
/**
|
|
114
|
+
* Controls the orderNo strategy when hasOrderNo is true.
|
|
115
|
+
* true — numeric ordering (10, 20, 30...)
|
|
116
|
+
* false — lexicographic string ordering via StrOrderHelpers
|
|
117
|
+
*/
|
|
35
118
|
orderNoAsDecimal?: boolean;
|
|
119
|
+
/**
|
|
120
|
+
* The ID type this core operates with (UUID, integer, etc.).
|
|
121
|
+
* Used by consumers that need to validate or coerce ID formats.
|
|
122
|
+
* Defaults to ID_TYPES.UNKNOWN if not set.
|
|
123
|
+
*/
|
|
36
124
|
idType?: ID_TYPES;
|
|
125
|
+
/**
|
|
126
|
+
* Per-core rate-limiter override. When set, BaseCore uses this instance
|
|
127
|
+
* instead of the app-level context.rateLimiter singleton. Typed structurally
|
|
128
|
+
* via RateLimiterInterface — any compatible implementation works.
|
|
129
|
+
*
|
|
130
|
+
* The normal path is to leave this unset and place one IpRateLimiter on
|
|
131
|
+
* context.rateLimiter at app startup so all cores share it automatically.
|
|
132
|
+
* Use this field only when a specific core needs a different limiter
|
|
133
|
+
* (e.g. a stricter in-memory limiter for a payment core in tests, or a
|
|
134
|
+
* no-op stub when integrating with an external rate-limiting proxy).
|
|
135
|
+
*
|
|
136
|
+
* Set to null to explicitly disable rate limiting for this core even when
|
|
137
|
+
* context.rateLimiter is configured.
|
|
138
|
+
*/
|
|
139
|
+
rateLimiter?: RateLimiterInterface | null;
|
|
140
|
+
/**
|
|
141
|
+
* Default rate-limit rule applied to every runAction call in this core
|
|
142
|
+
* unless overridden by rateLimitOnAction or CoreActionInterface.rateLimit.
|
|
143
|
+
*
|
|
144
|
+
* Example — limit all actions to 60 requests per minute:
|
|
145
|
+
* { limit: 60, windowSec: 60 }
|
|
146
|
+
*
|
|
147
|
+
* Omit to disable rate limiting at the core level (actions can still
|
|
148
|
+
* opt in individually via CoreActionInterface.rateLimit).
|
|
149
|
+
*/
|
|
150
|
+
rateLimit?: RateLimitRule;
|
|
151
|
+
/**
|
|
152
|
+
* Per-action rate-limit rules. An entry here replaces the core-level
|
|
153
|
+
* `rateLimit` rule for that specific action — core and action are
|
|
154
|
+
* mutually exclusive so a raised action limit is not silently capped
|
|
155
|
+
* by the core counter still running alongside it.
|
|
156
|
+
*
|
|
157
|
+
* The global counter (context.globalRateLimit) always runs independently
|
|
158
|
+
* and is never affected by entries here.
|
|
159
|
+
*
|
|
160
|
+
* Use a RateLimitRule to override the core default for an action.
|
|
161
|
+
* Use false to disable the core-or-action tier for that action entirely
|
|
162
|
+
* so only the global counter applies.
|
|
163
|
+
*
|
|
164
|
+
* Example — raise the limit for uploads, tighten sign-in, drop reads
|
|
165
|
+
* down to global-only:
|
|
166
|
+
* {
|
|
167
|
+
* list: false,
|
|
168
|
+
* get: false,
|
|
169
|
+
* create: { limit: 50, windowSec: 60 }, // replaces core rule
|
|
170
|
+
* update: { limit: 5, windowSec: 300 }, // tighter than core
|
|
171
|
+
* }
|
|
172
|
+
*/
|
|
173
|
+
rateLimitOnAction?: BaseCoreRateLimitOnActionInterface;
|
|
37
174
|
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export interface BaseExternalApiGatewayPropsInterface {
|
|
2
|
+
/**
|
|
3
|
+
* Optional credentials — a plain API key string or a structured object
|
|
4
|
+
* with whatever keys the external service requires.
|
|
5
|
+
* Can also be set later via setCredentials() once resolved at runtime.
|
|
6
|
+
*/
|
|
7
|
+
credentials?: string | Record<string, any>;
|
|
8
|
+
/**
|
|
9
|
+
* Base URL of the external API.
|
|
10
|
+
* Can be overridden in the subclass if it never changes.
|
|
11
|
+
*/
|
|
12
|
+
baseUrl?: string;
|
|
13
|
+
/**
|
|
14
|
+
* Timeout in milliseconds for outbound requests.
|
|
15
|
+
* Defaults to 10000.
|
|
16
|
+
*/
|
|
17
|
+
timeoutMs?: number;
|
|
18
|
+
logger?: any;
|
|
19
|
+
}
|
|
@@ -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;
|
|
@@ -1,8 +1,25 @@
|
|
|
1
1
|
import { BaseCoreActionsInterface } from './BaseCoreActionsInterface';
|
|
2
|
+
import { RateLimitRule } from '../IpRateLimiter';
|
|
2
3
|
export interface CoreActionInterface {
|
|
3
4
|
args: any;
|
|
4
5
|
actionName?: string;
|
|
5
6
|
doAuth?: boolean;
|
|
7
|
+
/**
|
|
8
|
+
* When true, attempts authentication but does not fail if it does not succeed.
|
|
9
|
+
* If a valid JWT is present, context will be populated with accountId, userId,
|
|
10
|
+
* roleId, etc. as normal. If no token is present or verification fails, the
|
|
11
|
+
* request continues unauthenticated with no error returned.
|
|
12
|
+
*
|
|
13
|
+
* Use for public endpoints that behave differently for authenticated users
|
|
14
|
+
* (e.g. personalised content, showing ownership state, soft-gating features).
|
|
15
|
+
*
|
|
16
|
+
* Runs before `requireSpace` — if soft auth populates the context, space
|
|
17
|
+
* verification will have the enriched context available.
|
|
18
|
+
*
|
|
19
|
+
* Mutually exclusive intent with `doAuth` — if `doAuth` is true, this flag
|
|
20
|
+
* is ignored since a hard auth failure is already enforced.
|
|
21
|
+
*/
|
|
22
|
+
tryAuth?: boolean;
|
|
6
23
|
accessRights?: any[];
|
|
7
24
|
roles?: string[];
|
|
8
25
|
validate?(args: any, opt: BaseCoreActionsInterface): Promise<any[]> | any[];
|
|
@@ -12,5 +29,48 @@ export interface CoreActionInterface {
|
|
|
12
29
|
onException?(params: any, opt?: BaseCoreActionsInterface): Promise<any | undefined | null>;
|
|
13
30
|
shouldLogArgs?: boolean;
|
|
14
31
|
requireSpace?: boolean;
|
|
32
|
+
/**
|
|
33
|
+
* When true, lets runAction skip the action result check that decides
|
|
34
|
+
* whether to commit or rollback the DB transaction.
|
|
35
|
+
*/
|
|
15
36
|
skipCheckResult?: boolean;
|
|
37
|
+
/**
|
|
38
|
+
* Action-scoped rate-limit rule for this specific runAction call.
|
|
39
|
+
*
|
|
40
|
+
* Overrides the core-or-action tier for this specific runAction call.
|
|
41
|
+
* Action and core rules are mutually exclusive — this rule replaces the
|
|
42
|
+
* core rule (config.rateLimit) for this call so that loosening or
|
|
43
|
+
* tightening the limit here has full effect without the core counter
|
|
44
|
+
* silently capping it.
|
|
45
|
+
*
|
|
46
|
+
* The global counter (context.globalRateLimit) always runs independently
|
|
47
|
+
* alongside this and is never affected by this field.
|
|
48
|
+
*
|
|
49
|
+
* Set to a RateLimitRule to apply or override the action-level limit.
|
|
50
|
+
* This takes precedence over rateLimitOnAction[actionName] when both
|
|
51
|
+
* are configured — only one core-or-action counter runs per request.
|
|
52
|
+
*
|
|
53
|
+
* Set to false to disable the core-or-action tier for this call entirely
|
|
54
|
+
* so only the global counter applies.
|
|
55
|
+
*
|
|
56
|
+
* Evaluated before the DB transaction is opened and before authentication,
|
|
57
|
+
* so auth endpoints are protected from brute-force attempts without any
|
|
58
|
+
* DB or session overhead.
|
|
59
|
+
*
|
|
60
|
+
* Same-request nested calls (sameRequest === true) always skip all rate
|
|
61
|
+
* limiting — the outer call has already consumed the counter slots.
|
|
62
|
+
*
|
|
63
|
+
* Example — tighten limits on a sensitive mutation:
|
|
64
|
+
* runAction({
|
|
65
|
+
* ...,
|
|
66
|
+
* rateLimit: { limit: 5, windowSec: 300 },
|
|
67
|
+
* })
|
|
68
|
+
*
|
|
69
|
+
* Example — disable the action-level counter for an internal helper:
|
|
70
|
+
* runAction({
|
|
71
|
+
* ...,
|
|
72
|
+
* rateLimit: false,
|
|
73
|
+
* })
|
|
74
|
+
*/
|
|
75
|
+
rateLimit?: RateLimitRule | false;
|
|
16
76
|
}
|
|
@@ -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
|
+
}
|