@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.
Files changed (214) hide show
  1. package/README.md +1422 -146
  2. package/build/BaseController.d.ts +20 -0
  3. package/build/BaseController.js +64 -0
  4. package/build/BaseCore.d.ts +586 -33
  5. package/build/BaseCore.js +821 -127
  6. package/build/BaseExternalApiGateway.d.ts +16 -0
  7. package/build/BaseExternalApiGateway.js +54 -0
  8. package/build/BaseGateway.d.ts +455 -17
  9. package/build/BaseGateway.js +502 -56
  10. package/build/BaseRestApiCrudController.d.ts +37 -0
  11. package/build/BaseRestApiCrudController.js +134 -0
  12. package/build/DataCache.d.ts +116 -5
  13. package/build/DataCache.js +144 -22
  14. package/build/Database.d.ts +165 -4
  15. package/build/Database.js +224 -51
  16. package/build/DbMigratorAndSeeder.d.ts +127 -26
  17. package/build/DbMigratorAndSeeder.js +180 -69
  18. package/build/IpRateLimiter.d.ts +105 -0
  19. package/build/IpRateLimiter.js +104 -0
  20. package/build/RedisDataLoader.d.ts +144 -21
  21. package/build/RedisDataLoader.js +178 -49
  22. package/build/apiContext.d.ts +0 -8
  23. package/build/apiContext.js +30 -32
  24. package/build/checkItHelpers.d.ts +32 -0
  25. package/build/checkItHelpers.js +73 -7
  26. package/build/commonValidators.d.ts +107 -16
  27. package/build/commonValidators.js +211 -106
  28. package/build/configBuilder.d.ts +23 -0
  29. package/build/configBuilder.js +73 -0
  30. package/build/constants.d.ts +134 -17
  31. package/build/constants.js +95 -15
  32. package/build/dbHelpers.d.ts +89 -29
  33. package/build/dbHelpers.js +175 -86
  34. package/build/dbSeeder.d.ts +10 -1
  35. package/build/dbSeeder.js +80 -15
  36. package/build/dbTableHelpers.d.ts +122 -5
  37. package/build/dbTableHelpers.js +151 -13
  38. package/build/downloadHelpers.d.ts +24 -1
  39. package/build/downloadHelpers.js +51 -21
  40. package/build/esm/BaseController.d.ts +20 -0
  41. package/build/esm/BaseController.js +58 -0
  42. package/build/esm/BaseCore.d.ts +586 -33
  43. package/build/esm/BaseCore.js +812 -118
  44. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  45. package/build/esm/BaseExternalApiGateway.js +48 -0
  46. package/build/esm/BaseGateway.d.ts +455 -17
  47. package/build/esm/BaseGateway.js +503 -57
  48. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  49. package/build/esm/BaseRestApiCrudController.js +131 -0
  50. package/build/esm/DataCache.d.ts +116 -5
  51. package/build/esm/DataCache.js +142 -20
  52. package/build/esm/Database.d.ts +165 -4
  53. package/build/esm/Database.js +224 -51
  54. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  55. package/build/esm/DbMigratorAndSeeder.js +184 -71
  56. package/build/esm/IpRateLimiter.d.ts +105 -0
  57. package/build/esm/IpRateLimiter.js +100 -0
  58. package/build/esm/RedisDataLoader.d.ts +144 -21
  59. package/build/esm/RedisDataLoader.js +179 -50
  60. package/build/esm/apiContext.d.ts +0 -8
  61. package/build/esm/apiContext.js +30 -32
  62. package/build/esm/checkItHelpers.d.ts +32 -0
  63. package/build/esm/checkItHelpers.js +73 -7
  64. package/build/esm/commonValidators.d.ts +107 -16
  65. package/build/esm/commonValidators.js +209 -105
  66. package/build/esm/configBuilder.d.ts +23 -0
  67. package/build/esm/configBuilder.js +69 -0
  68. package/build/esm/constants.d.ts +134 -17
  69. package/build/esm/constants.js +94 -14
  70. package/build/esm/dbHelpers.d.ts +89 -29
  71. package/build/esm/dbHelpers.js +171 -81
  72. package/build/esm/dbSeeder.d.ts +10 -1
  73. package/build/esm/dbSeeder.js +81 -16
  74. package/build/esm/dbTableHelpers.d.ts +122 -5
  75. package/build/esm/dbTableHelpers.js +152 -14
  76. package/build/esm/downloadHelpers.d.ts +24 -1
  77. package/build/esm/downloadHelpers.js +51 -21
  78. package/build/esm/index.d.ts +6 -2
  79. package/build/esm/index.js +6 -2
  80. package/build/esm/interfaces/ApiContext.d.ts +33 -3
  81. package/build/esm/interfaces/ApiContext.js +1 -0
  82. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  83. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  84. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  85. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  86. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  87. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +146 -9
  88. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  89. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  90. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  91. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  92. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  93. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  94. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  95. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  96. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  97. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  98. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  99. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  100. package/build/esm/interfaces/CacheInterface.js +1 -0
  101. package/build/esm/interfaces/CoreActionInterface.d.ts +60 -0
  102. package/build/esm/interfaces/CoreActionInterface.js +1 -0
  103. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  104. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  105. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  106. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  107. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  108. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  109. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  110. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  111. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  112. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  113. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  114. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  115. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  116. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  117. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  118. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  119. package/build/esm/interfaces/LoaderInterface.js +1 -0
  120. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  121. package/build/esm/interfaces/UserTokenParams.js +1 -0
  122. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  123. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  124. package/build/esm/interfaces/index.d.ts +4 -0
  125. package/build/esm/interfaces/index.js +4 -0
  126. package/build/esm/knexConfigBuilder.d.ts +25 -0
  127. package/build/esm/knexConfigBuilder.js +100 -36
  128. package/build/esm/parseIds.d.ts +6 -0
  129. package/build/esm/parseIds.js +13 -0
  130. package/build/esm/passwordHelpers.d.ts +22 -0
  131. package/build/esm/passwordHelpers.js +40 -8
  132. package/build/esm/redisClient.d.ts +57 -4
  133. package/build/esm/redisClient.js +40 -54
  134. package/build/esm/resolveClientIp.d.ts +15 -0
  135. package/build/esm/resolveClientIp.js +34 -0
  136. package/build/esm/resolversHelpers.d.ts +21 -1
  137. package/build/esm/resolversHelpers.js +48 -26
  138. package/build/esm/userToken.d.ts +50 -1
  139. package/build/esm/userToken.js +85 -20
  140. package/build/esm/utils.d.ts +20 -2
  141. package/build/esm/utils.js +23 -13
  142. package/build/index.d.ts +6 -2
  143. package/build/index.js +6 -2
  144. package/build/interfaces/ApiContext.d.ts +33 -3
  145. package/build/interfaces/ApiContext.js +1 -0
  146. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  147. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  148. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  149. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  150. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  151. package/build/interfaces/BaseCorePropsInterface.d.ts +146 -9
  152. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  153. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  154. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  155. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  156. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  157. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  158. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  159. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  160. package/build/interfaces/BuildConfigOptions.js +1 -0
  161. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  162. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  163. package/build/interfaces/CacheInterface.d.ts +18 -1
  164. package/build/interfaces/CacheInterface.js +1 -0
  165. package/build/interfaces/CoreActionInterface.d.ts +60 -0
  166. package/build/interfaces/CoreActionInterface.js +1 -0
  167. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  168. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  169. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  170. package/build/interfaces/DataCachePropsInterface.js +3 -0
  171. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  172. package/build/interfaces/DatabaseOptions.js +1 -0
  173. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  174. package/build/interfaces/DatabaseReadInterface.js +1 -0
  175. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  176. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  177. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  178. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  179. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  180. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  181. package/build/interfaces/ListArgsInterface.js +1 -0
  182. package/build/interfaces/LoaderInterface.d.ts +36 -1
  183. package/build/interfaces/LoaderInterface.js +1 -0
  184. package/build/interfaces/UserTokenParams.d.ts +23 -5
  185. package/build/interfaces/UserTokenParams.js +1 -0
  186. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  187. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  188. package/build/interfaces/index.d.ts +4 -0
  189. package/build/interfaces/index.js +4 -0
  190. package/build/knexConfigBuilder.d.ts +25 -0
  191. package/build/knexConfigBuilder.js +99 -35
  192. package/build/parseIds.d.ts +6 -0
  193. package/build/parseIds.js +17 -0
  194. package/build/passwordHelpers.d.ts +22 -0
  195. package/build/passwordHelpers.js +40 -8
  196. package/build/redisClient.d.ts +57 -4
  197. package/build/redisClient.js +40 -54
  198. package/build/resolveClientIp.d.ts +15 -0
  199. package/build/resolveClientIp.js +38 -0
  200. package/build/resolversHelpers.d.ts +21 -1
  201. package/build/resolversHelpers.js +48 -26
  202. package/build/userToken.d.ts +50 -1
  203. package/build/userToken.js +85 -20
  204. package/build/utils.d.ts +20 -2
  205. package/build/utils.js +24 -16
  206. package/package.json +19 -18
  207. package/build/baseController.d.ts +0 -17
  208. package/build/baseController.js +0 -64
  209. package/build/configBulder.d.ts +0 -2
  210. package/build/configBulder.js +0 -36
  211. package/build/esm/baseController.d.ts +0 -17
  212. package/build/esm/baseController.js +0 -58
  213. package/build/esm/configBulder.d.ts +0 -2
  214. package/build/esm/configBulder.js +0 -32
@@ -1,26 +1,40 @@
1
- import { Logger } from '@sdflc/utils';
2
1
  /**
3
- * Interface to initialize Database object
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: pg, msql, etc
17
+ * Database driver type (e.g. 'pg', 'mysql2', 'sqlite3').
18
+ * Optional — falls back to `knexConfig.client` if not provided.
12
19
  */
13
- dbType: string;
20
+ dbType?: string;
14
21
  /**
15
- * Name of database schema
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: string;
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 debugging/logging
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?: Logger;
39
+ logger?: any;
26
40
  }
@@ -1 +1,2 @@
1
+ // ./src/interfaces/DatabaseOptions.ts
1
2
  export {};
@@ -1,14 +1,69 @@
1
1
  /**
2
- * Interface for Database.ReadAll method
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
- whereIn?: any;
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
- buildKey?(key: string): string;
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 +1,2 @@
1
+ // ./src/interfaces/DatabaseReadInterface.ts
1
2
  export {};
@@ -1,9 +1,40 @@
1
1
  export interface DbFieldAddDefaultInterface {
2
- addUserInfo?: boolean;
3
- addVersion?: boolean;
2
+ /**
3
+ * When true, adds a `status` integer column (indexed) with default STATUSES.ACTIVE.
4
+ */
4
5
  addStatus?: boolean;
5
- skipTimestamps?: boolean;
6
- skipRemovedAtStr?: boolean;
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 +1,2 @@
1
+ // ./src/interfaces/DbFieldAddDefaultInterface.ts
1
2
  export {};
@@ -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
- fileName: string;
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
- stream?: any;
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
- * Req is a request object of the Express library
3
+ * Express request object. Used to read cookies and headers.
4
4
  */
5
5
  req: any;
6
6
  /**
7
- * Space is an object with configuration where to get data from
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 is a token from the Authorization header
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
- * An object with parameters passed to the authenticate methods
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 +1,2 @@
1
+ // ./src/interfaces/ExtractCredentialsArgs.ts
1
2
  export {};
@@ -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 +1,2 @@
1
+ // ./src/interfaces/ListArgsInterface.ts
1
2
  export {};
@@ -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
- loadMany(id: any): Promise<any[]>;
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 +1,2 @@
1
+ // ./src/interfaces/LoaderInterface.ts
1
2
  export {};
@@ -1,8 +1,26 @@
1
1
  export interface UserTokenParams {
2
- spaceId: string;
3
- accountId: string;
4
- roleId: string;
2
+ /**
3
+ * The user's ID — used as the JWT `subject` claim. Required.
4
+ */
5
5
  userId: string;
6
- lang: string;
7
- [tokenProp: string]: string;
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 +1,2 @@
1
+ // ./src/interfaces/UserTokenParams.ts
1
2
  export {};
@@ -1,13 +1,53 @@
1
1
  export interface VerifyUserTokenArgs {
2
- algorithms?: any;
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
- maxAge?: number;
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
  }
@@ -1 +1,2 @@
1
+ // ./src/interfaces/VerifyUserTokenArgs.ts
1
2
  export {};
@@ -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, get } from 'lodash';
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 sharedConfig = {
17
- client: dbType || 'pg',
18
- postProcessResponse: camelResponse,
19
- wrapIdentifier: (value, origImpl) => {
20
- if (value === '*') {
21
- return origImpl(value);
22
- }
23
- const value2use = wrapIdentifierOverrideMap?.[value] || origImpl(snakeCase(value));
24
- return value2use;
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
- if (typeof dbPool === 'object') {
36
- sharedConfig.pool = dbPool;
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
- else {
39
- sharedConfig.pool = {
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
- // https://knexjs.org/guide/migrations.html#migration-api
126
+ // stub is only needed in development (used by `knex migrate:make`)
57
127
  stub: path.join(dirName, migrationsTemplateFileName || defaultMigrationsTemplateFileName),
58
- directory: path.join(dirName, migrationsFolder || defaultMigrationsFolder),
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
- directory: path.join(dirName, migrationsFolder || defaultMigrationsFolder),
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
- let config2use = get(config, nodeEnv);
80
- if (!config2use) {
81
- config2use = config.development;
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[]];