@sdflc/backend-helpers 1.0.112 → 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.
Files changed (206) 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 +470 -33
  5. package/build/BaseCore.js +608 -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/RedisDataLoader.d.ts +144 -21
  19. package/build/RedisDataLoader.js +178 -49
  20. package/build/apiContext.d.ts +0 -8
  21. package/build/apiContext.js +12 -27
  22. package/build/checkItHelpers.d.ts +32 -0
  23. package/build/checkItHelpers.js +73 -7
  24. package/build/commonValidators.d.ts +107 -16
  25. package/build/commonValidators.js +211 -106
  26. package/build/configBuilder.d.ts +23 -0
  27. package/build/configBuilder.js +73 -0
  28. package/build/constants.d.ts +134 -17
  29. package/build/constants.js +95 -15
  30. package/build/dbHelpers.d.ts +89 -29
  31. package/build/dbHelpers.js +175 -86
  32. package/build/dbSeeder.d.ts +10 -1
  33. package/build/dbSeeder.js +80 -15
  34. package/build/dbTableHelpers.d.ts +122 -5
  35. package/build/dbTableHelpers.js +151 -13
  36. package/build/downloadHelpers.d.ts +24 -1
  37. package/build/downloadHelpers.js +51 -21
  38. package/build/esm/BaseController.d.ts +20 -0
  39. package/build/esm/BaseController.js +58 -0
  40. package/build/esm/BaseCore.d.ts +470 -33
  41. package/build/esm/BaseCore.js +599 -118
  42. package/build/esm/BaseExternalApiGateway.d.ts +16 -0
  43. package/build/esm/BaseExternalApiGateway.js +48 -0
  44. package/build/esm/BaseGateway.d.ts +455 -17
  45. package/build/esm/BaseGateway.js +503 -57
  46. package/build/esm/BaseRestApiCrudController.d.ts +37 -0
  47. package/build/esm/BaseRestApiCrudController.js +131 -0
  48. package/build/esm/DataCache.d.ts +116 -5
  49. package/build/esm/DataCache.js +142 -20
  50. package/build/esm/Database.d.ts +165 -4
  51. package/build/esm/Database.js +224 -51
  52. package/build/esm/DbMigratorAndSeeder.d.ts +127 -26
  53. package/build/esm/DbMigratorAndSeeder.js +184 -71
  54. package/build/esm/RedisDataLoader.d.ts +144 -21
  55. package/build/esm/RedisDataLoader.js +179 -50
  56. package/build/esm/apiContext.d.ts +0 -8
  57. package/build/esm/apiContext.js +12 -27
  58. package/build/esm/checkItHelpers.d.ts +32 -0
  59. package/build/esm/checkItHelpers.js +73 -7
  60. package/build/esm/commonValidators.d.ts +107 -16
  61. package/build/esm/commonValidators.js +209 -105
  62. package/build/esm/configBuilder.d.ts +23 -0
  63. package/build/esm/configBuilder.js +69 -0
  64. package/build/esm/constants.d.ts +134 -17
  65. package/build/esm/constants.js +94 -14
  66. package/build/esm/dbHelpers.d.ts +89 -29
  67. package/build/esm/dbHelpers.js +171 -81
  68. package/build/esm/dbSeeder.d.ts +10 -1
  69. package/build/esm/dbSeeder.js +81 -16
  70. package/build/esm/dbTableHelpers.d.ts +122 -5
  71. package/build/esm/dbTableHelpers.js +152 -14
  72. package/build/esm/downloadHelpers.d.ts +24 -1
  73. package/build/esm/downloadHelpers.js +51 -21
  74. package/build/esm/index.d.ts +5 -2
  75. package/build/esm/index.js +5 -2
  76. package/build/esm/interfaces/ApiContext.d.ts +7 -3
  77. package/build/esm/interfaces/ApiContextInterface.d.ts +1 -1
  78. package/build/esm/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  79. package/build/esm/interfaces/BaseControllerPropsInterface.js +1 -0
  80. package/build/esm/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  81. package/build/esm/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  82. package/build/esm/interfaces/BaseCorePropsInterface.d.ts +87 -9
  83. package/build/esm/interfaces/BaseCorePropsInterface.js +1 -0
  84. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  85. package/build/esm/interfaces/BaseExternalApiGatewayPropsInterface.js +2 -0
  86. package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  87. package/build/esm/interfaces/BaseGatewayPropsInterface.js +1 -0
  88. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  89. package/build/esm/interfaces/BaseRestApiCrudControllerPropsInterface.js +2 -0
  90. package/build/esm/interfaces/BuildConfigOptions.d.ts +18 -0
  91. package/build/esm/interfaces/BuildConfigOptions.js +1 -0
  92. package/build/esm/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  93. package/build/esm/interfaces/BuildListQueryArgsInterface.js +1 -0
  94. package/build/esm/interfaces/CacheInterface.d.ts +18 -1
  95. package/build/esm/interfaces/CacheInterface.js +1 -0
  96. package/build/esm/interfaces/CoreActionInterface.d.ts +20 -0
  97. package/build/esm/interfaces/CreateUserTokenArgs.d.ts +38 -4
  98. package/build/esm/interfaces/CreateUserTokenArgs.js +1 -0
  99. package/build/esm/interfaces/DataCachePropsInterface.d.ts +21 -0
  100. package/build/esm/interfaces/DataCachePropsInterface.js +2 -0
  101. package/build/esm/interfaces/DatabaseOptions.d.ts +24 -10
  102. package/build/esm/interfaces/DatabaseOptions.js +1 -0
  103. package/build/esm/interfaces/DatabaseReadInterface.d.ts +58 -3
  104. package/build/esm/interfaces/DatabaseReadInterface.js +1 -0
  105. package/build/esm/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  106. package/build/esm/interfaces/DbFieldAddDefaultInterface.js +1 -0
  107. package/build/esm/interfaces/DownloadFileArgs.d.ts +21 -2
  108. package/build/esm/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  109. package/build/esm/interfaces/ExtractCredentialsArgs.js +1 -0
  110. package/build/esm/interfaces/ListArgsInterface.d.ts +18 -0
  111. package/build/esm/interfaces/ListArgsInterface.js +1 -0
  112. package/build/esm/interfaces/LoaderInterface.d.ts +36 -1
  113. package/build/esm/interfaces/LoaderInterface.js +1 -0
  114. package/build/esm/interfaces/UserTokenParams.d.ts +23 -5
  115. package/build/esm/interfaces/UserTokenParams.js +1 -0
  116. package/build/esm/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  117. package/build/esm/interfaces/VerifyUserTokenArgs.js +1 -0
  118. package/build/esm/interfaces/index.d.ts +4 -0
  119. package/build/esm/interfaces/index.js +4 -0
  120. package/build/esm/knexConfigBuilder.d.ts +25 -0
  121. package/build/esm/knexConfigBuilder.js +100 -36
  122. package/build/esm/parseIds.d.ts +6 -0
  123. package/build/esm/parseIds.js +13 -0
  124. package/build/esm/passwordHelpers.d.ts +22 -0
  125. package/build/esm/passwordHelpers.js +40 -8
  126. package/build/esm/redisClient.d.ts +57 -4
  127. package/build/esm/redisClient.js +40 -54
  128. package/build/esm/resolveClientIp.d.ts +15 -0
  129. package/build/esm/resolveClientIp.js +34 -0
  130. package/build/esm/resolversHelpers.d.ts +21 -1
  131. package/build/esm/resolversHelpers.js +48 -26
  132. package/build/esm/userToken.d.ts +50 -1
  133. package/build/esm/userToken.js +85 -20
  134. package/build/esm/utils.d.ts +20 -2
  135. package/build/esm/utils.js +23 -13
  136. package/build/index.d.ts +5 -2
  137. package/build/index.js +5 -2
  138. package/build/interfaces/ApiContext.d.ts +7 -3
  139. package/build/interfaces/ApiContextInterface.d.ts +1 -1
  140. package/build/interfaces/BaseControllerPropsInterface.d.ts +5 -0
  141. package/build/interfaces/BaseControllerPropsInterface.js +2 -0
  142. package/build/interfaces/BaseCoreDoAuthOnActionInterface.d.ts +1 -0
  143. package/build/interfaces/BaseCoreDoingWhatInterface.d.ts +11 -11
  144. package/build/interfaces/BaseCorePropsInterface.d.ts +87 -9
  145. package/build/interfaces/BaseCorePropsInterface.js +1 -0
  146. package/build/interfaces/BaseExternalApiGatewayPropsInterface.d.ts +19 -0
  147. package/build/interfaces/BaseExternalApiGatewayPropsInterface.js +3 -0
  148. package/build/interfaces/BaseGatewayPropsInterface.d.ts +78 -3
  149. package/build/interfaces/BaseGatewayPropsInterface.js +1 -0
  150. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.d.ts +28 -0
  151. package/build/interfaces/BaseRestApiCrudControllerPropsInterface.js +3 -0
  152. package/build/interfaces/BuildConfigOptions.d.ts +18 -0
  153. package/build/interfaces/BuildConfigOptions.js +1 -0
  154. package/build/interfaces/BuildListQueryArgsInterface.d.ts +22 -4
  155. package/build/interfaces/BuildListQueryArgsInterface.js +1 -0
  156. package/build/interfaces/CacheInterface.d.ts +18 -1
  157. package/build/interfaces/CacheInterface.js +1 -0
  158. package/build/interfaces/CoreActionInterface.d.ts +20 -0
  159. package/build/interfaces/CreateUserTokenArgs.d.ts +38 -4
  160. package/build/interfaces/CreateUserTokenArgs.js +1 -0
  161. package/build/interfaces/DataCachePropsInterface.d.ts +21 -0
  162. package/build/interfaces/DataCachePropsInterface.js +3 -0
  163. package/build/interfaces/DatabaseOptions.d.ts +24 -10
  164. package/build/interfaces/DatabaseOptions.js +1 -0
  165. package/build/interfaces/DatabaseReadInterface.d.ts +58 -3
  166. package/build/interfaces/DatabaseReadInterface.js +1 -0
  167. package/build/interfaces/DbFieldAddDefaultInterface.d.ts +35 -4
  168. package/build/interfaces/DbFieldAddDefaultInterface.js +1 -0
  169. package/build/interfaces/DownloadFileArgs.d.ts +21 -2
  170. package/build/interfaces/ExtractCredentialsArgs.d.ts +15 -4
  171. package/build/interfaces/ExtractCredentialsArgs.js +1 -0
  172. package/build/interfaces/ListArgsInterface.d.ts +18 -0
  173. package/build/interfaces/ListArgsInterface.js +1 -0
  174. package/build/interfaces/LoaderInterface.d.ts +36 -1
  175. package/build/interfaces/LoaderInterface.js +1 -0
  176. package/build/interfaces/UserTokenParams.d.ts +23 -5
  177. package/build/interfaces/UserTokenParams.js +1 -0
  178. package/build/interfaces/VerifyUserTokenArgs.d.ts +42 -2
  179. package/build/interfaces/VerifyUserTokenArgs.js +1 -0
  180. package/build/interfaces/index.d.ts +4 -0
  181. package/build/interfaces/index.js +4 -0
  182. package/build/knexConfigBuilder.d.ts +25 -0
  183. package/build/knexConfigBuilder.js +99 -35
  184. package/build/parseIds.d.ts +6 -0
  185. package/build/parseIds.js +17 -0
  186. package/build/passwordHelpers.d.ts +22 -0
  187. package/build/passwordHelpers.js +40 -8
  188. package/build/redisClient.d.ts +57 -4
  189. package/build/redisClient.js +40 -54
  190. package/build/resolveClientIp.d.ts +15 -0
  191. package/build/resolveClientIp.js +38 -0
  192. package/build/resolversHelpers.d.ts +21 -1
  193. package/build/resolversHelpers.js +48 -26
  194. package/build/userToken.d.ts +50 -1
  195. package/build/userToken.js +85 -20
  196. package/build/utils.d.ts +20 -2
  197. package/build/utils.js +24 -16
  198. package/package.json +19 -18
  199. package/build/baseController.d.ts +0 -17
  200. package/build/baseController.js +0 -64
  201. package/build/configBulder.d.ts +0 -2
  202. package/build/configBulder.js +0 -36
  203. package/build/esm/baseController.d.ts +0 -17
  204. package/build/esm/baseController.js +0 -58
  205. package/build/esm/configBulder.d.ts +0 -2
  206. package/build/esm/configBulder.js +0 -32
@@ -1,30 +1,147 @@
1
- declare const FIELDS: any;
1
+ /**
2
+ * Standard database column names used across all gateway tables.
3
+ * Values are snake_case to match database conventions.
4
+ * Use camelCase() from lodash when mapping to JavaScript object keys.
5
+ *
6
+ * Note: used with `as const` so TypeScript infers narrow literal types,
7
+ * enabling compile-time catches of typos when accessing FIELDS.NONEXISTENT.
8
+ */
9
+ declare const FIELDS: {
10
+ readonly ID: "id";
11
+ readonly STATUS: "status";
12
+ readonly VERSION: "version";
13
+ readonly CREATED_BY: "created_by";
14
+ readonly UPDATED_BY: "updated_by";
15
+ readonly REMOVED_BY: "removed_by";
16
+ readonly CREATED_AT: "created_at";
17
+ readonly UPDATED_AT: "updated_at";
18
+ readonly REMOVED_AT: "removed_at";
19
+ readonly REMOVED_AT_STR: "removed_at_str";
20
+ readonly LANG: "lang";
21
+ readonly ACCOUNT_ID: "account_id";
22
+ readonly ROLE_ID: "role_id";
23
+ readonly USER_ID: "user_id";
24
+ readonly ORDER_NO: "order_no";
25
+ readonly SPACE_ID: "space_id";
26
+ readonly DISPLAY_NAME: "display_name";
27
+ readonly NAME: "name";
28
+ readonly USERNAME: "username";
29
+ readonly EMAIL: "email";
30
+ readonly PHONE: "phone";
31
+ readonly WEBSITE: "website";
32
+ readonly COUNTRY_ID: "country_id";
33
+ readonly COUNTRY_CODE: "country_code";
34
+ readonly COUNTRY: "country";
35
+ readonly CITY: "city";
36
+ readonly STATE_RPOVINCE: "state_province";
37
+ readonly POSTAL_CODE: "postal_code";
38
+ readonly STREET_ADDRESS: "street_address";
39
+ readonly PO_BOX: "po_box";
40
+ readonly ADDRESS_1: "address_1";
41
+ readonly ADDRESS_2: "address_2";
42
+ };
43
+ /**
44
+ * Sort direction values for use in sortBy clauses.
45
+ */
2
46
  declare const ORDER_BYS: {
3
- ASC: string;
4
- DESC: string;
47
+ readonly ASC: "asc";
48
+ readonly DESC: "desc";
49
+ };
50
+ /**
51
+ * HTTP header names used for reading request context in createContextDefault()
52
+ * and authenticate().
53
+ *
54
+ * All values are lowercase to match the HTTP/2 convention and how Express
55
+ * normalises header names on req.headers.
56
+ *
57
+ * IP resolution note:
58
+ * HEADERS.IP_ADDRESS ('x-real-ip') is an explicit pre-resolved IP override,
59
+ * typically set by nginx via `proxy_set_header X-Real-IP $remote_addr`.
60
+ * It takes priority over all other IP resolution strategies in resolveClientIp().
61
+ *
62
+ * The standard proxy chain header 'x-forwarded-for' is handled separately
63
+ * inside resolveClientIp() and is NOT represented here as a named constant
64
+ * to avoid confusion between the two different resolution strategies.
65
+ */
66
+ declare const HEADERS: {
67
+ readonly AUTHORIZATION: "authorization";
68
+ readonly FINGERPRINT: "x-fingerprint";
69
+ readonly SPACE_ID: "x-space-id";
70
+ readonly API_KEY: "x-api-key";
71
+ readonly MANAGEMENT_API_KEY: "x-management-api-key";
72
+ readonly ACCOUNT_ID: "x-account-id";
73
+ readonly ROLE_ID: "x-role-id";
74
+ readonly USER_ID: "x-user-id";
75
+ readonly USER_AGENT: "user-agent";
76
+ readonly REFERER: "referer";
77
+ /**
78
+ * Explicit pre-resolved client IP override.
79
+ * Set by nginx via `proxy_set_header X-Real-IP $remote_addr`.
80
+ * Takes priority over x-forwarded-for and socket address in resolveClientIp().
81
+ */
82
+ readonly IP_ADDRESS: "x-real-ip";
83
+ readonly ACCEPT_LANGUAGE: "accept-language";
84
+ readonly REQUESTED_LANGUAGE: "x-lang";
85
+ readonly CONTENT_TYPE: "content-type";
86
+ readonly CONTENT_LENGTH: "content-length";
87
+ };
88
+ /**
89
+ * Action name constants used in runAction() for logging and access control.
90
+ * Match the operation names on BaseCore and BaseGateway.
91
+ */
92
+ declare const ACTIONS: {
93
+ readonly LIST: "LIST";
94
+ readonly GET: "GET";
95
+ readonly GET_MANY: "GET_MANY";
96
+ readonly CREATE: "CREATE";
97
+ readonly CREATE_MANY: "CREATE_MANY";
98
+ readonly UPDATE: "UPDATE";
99
+ readonly UPDATE_MANY: "UPDATE_MANY";
100
+ readonly SET: "SET";
101
+ readonly REMOVE: "REMOVE";
102
+ readonly REMOVE_MANY: "REMOVE_MANY";
5
103
  };
6
- declare const HEADERS: any;
104
+ /**
105
+ * ID type discriminator used by BaseCore.getIdType() to select the
106
+ * appropriate validator rule set in validateGet, validateGetMany,
107
+ * validateRemove, and validateRemoveMany.
108
+ */
7
109
  declare enum ID_TYPES {
8
110
  UNKNOWN = 0,
9
111
  INT = 1,
10
112
  UUID = 2,
11
113
  TEXT = 3
12
114
  }
13
- declare const ID_FIELD: any;
115
+ /**
116
+ * Default primary key field name. Used by BaseGateway when idField
117
+ * is not explicitly set in config.
118
+ */
119
+ declare const ID_FIELD: "id";
120
+ /**
121
+ * Default starting orderNo value for new sequences.
122
+ * Stored as a string because it is used with StrOrderHelpers for
123
+ * lexicographic ordering. Converted to Number() for decimal ordering.
124
+ * The large value leaves room for manual insertions before the first
125
+ * auto-assigned record.
126
+ */
14
127
  declare const DEFAULT_ORDER_NO = "10000000";
128
+ /**
129
+ * Default increment step for orderNo sequences.
130
+ * Stored as a string for the same reason as DEFAULT_ORDER_NO.
131
+ * Large step allows records to be manually inserted between auto-assigned
132
+ * values without requiring a full renumber.
133
+ */
15
134
  declare const DEFAULT_ORDER_NO_STEP = "1000";
135
+ /**
136
+ * Default JWT signing algorithm.
137
+ * HS256 (HMAC-SHA256) — symmetric, suitable for single-service tokens.
138
+ * Override via verifyTokenArgs.algorithms for RS256 or other asymmetric algorithms.
139
+ */
16
140
  declare const DEFAULT_JWT_ALGORITHM = "HS256";
141
+ /**
142
+ * Default JWT issuer claim value.
143
+ * Verified during token validation in authenticate().
144
+ * Override via verifyTokenArgs.issuer for service-specific issuers.
145
+ */
17
146
  declare const DEFAULT_JWT_ISSUER = "microservices-auth";
18
- declare const ACTIONS: {
19
- LIST: string;
20
- GET: string;
21
- GET_MANY: string;
22
- CREATE: string;
23
- CREATE_MANY: string;
24
- UPDATE: string;
25
- UPDATE_MANY: string;
26
- SET: string;
27
- REMOVE: string;
28
- REMOVE_MANY: string;
29
- };
30
147
  export { ID_FIELD, FIELDS, ORDER_BYS, HEADERS, DEFAULT_ORDER_NO, DEFAULT_ORDER_NO_STEP, ID_TYPES, DEFAULT_JWT_ALGORITHM, DEFAULT_JWT_ISSUER, ACTIONS, };
@@ -1,3 +1,12 @@
1
+ // ./src/constants.ts
2
+ /**
3
+ * Standard database column names used across all gateway tables.
4
+ * Values are snake_case to match database conventions.
5
+ * Use camelCase() from lodash when mapping to JavaScript object keys.
6
+ *
7
+ * Note: used with `as const` so TypeScript infers narrow literal types,
8
+ * enabling compile-time catches of typos when accessing FIELDS.NONEXISTENT.
9
+ */
1
10
  const FIELDS = {
2
11
  ID: 'id',
3
12
  STATUS: 'status',
@@ -9,7 +18,7 @@ const FIELDS = {
9
18
  UPDATED_AT: 'updated_at',
10
19
  REMOVED_AT: 'removed_at',
11
20
  REMOVED_AT_STR: 'removed_at_str',
12
- LANG: 'LANG',
21
+ LANG: 'lang',
13
22
  ACCOUNT_ID: 'account_id',
14
23
  ROLE_ID: 'role_id',
15
24
  USER_ID: 'user_id',
@@ -20,11 +29,41 @@ const FIELDS = {
20
29
  USERNAME: 'username',
21
30
  EMAIL: 'email',
22
31
  PHONE: 'phone',
32
+ WEBSITE: 'website',
33
+ COUNTRY_ID: 'country_id',
34
+ COUNTRY_CODE: 'country_code',
35
+ COUNTRY: 'country',
36
+ CITY: 'city',
37
+ STATE_RPOVINCE: 'state_province',
38
+ POSTAL_CODE: 'postal_code',
39
+ STREET_ADDRESS: 'street_address',
40
+ PO_BOX: 'po_box',
41
+ ADDRESS_1: 'address_1',
42
+ ADDRESS_2: 'address_2',
23
43
  };
44
+ /**
45
+ * Sort direction values for use in sortBy clauses.
46
+ */
24
47
  const ORDER_BYS = {
25
48
  ASC: 'asc',
26
49
  DESC: 'desc',
27
50
  };
51
+ /**
52
+ * HTTP header names used for reading request context in createContextDefault()
53
+ * and authenticate().
54
+ *
55
+ * All values are lowercase to match the HTTP/2 convention and how Express
56
+ * normalises header names on req.headers.
57
+ *
58
+ * IP resolution note:
59
+ * HEADERS.IP_ADDRESS ('x-real-ip') is an explicit pre-resolved IP override,
60
+ * typically set by nginx via `proxy_set_header X-Real-IP $remote_addr`.
61
+ * It takes priority over all other IP resolution strategies in resolveClientIp().
62
+ *
63
+ * The standard proxy chain header 'x-forwarded-for' is handled separately
64
+ * inside resolveClientIp() and is NOT represented here as a named constant
65
+ * to avoid confusion between the two different resolution strategies.
66
+ */
28
67
  const HEADERS = {
29
68
  AUTHORIZATION: 'authorization',
30
69
  FINGERPRINT: 'x-fingerprint',
@@ -36,24 +75,21 @@ const HEADERS = {
36
75
  USER_ID: 'x-user-id',
37
76
  USER_AGENT: 'user-agent',
38
77
  REFERER: 'referer',
39
- IP_ADDRESS: 'x-forwarded-for',
78
+ /**
79
+ * Explicit pre-resolved client IP override.
80
+ * Set by nginx via `proxy_set_header X-Real-IP $remote_addr`.
81
+ * Takes priority over x-forwarded-for and socket address in resolveClientIp().
82
+ */
83
+ IP_ADDRESS: 'x-real-ip',
40
84
  ACCEPT_LANGUAGE: 'accept-language',
41
85
  REQUESTED_LANGUAGE: 'x-lang',
42
86
  CONTENT_TYPE: 'content-type',
43
87
  CONTENT_LENGTH: 'content-length',
44
88
  };
45
- var ID_TYPES;
46
- (function (ID_TYPES) {
47
- ID_TYPES[ID_TYPES["UNKNOWN"] = 0] = "UNKNOWN";
48
- ID_TYPES[ID_TYPES["INT"] = 1] = "INT";
49
- ID_TYPES[ID_TYPES["UUID"] = 2] = "UUID";
50
- ID_TYPES[ID_TYPES["TEXT"] = 3] = "TEXT";
51
- })(ID_TYPES || (ID_TYPES = {}));
52
- const ID_FIELD = FIELDS.ID;
53
- const DEFAULT_ORDER_NO = '10000000';
54
- const DEFAULT_ORDER_NO_STEP = '1000';
55
- const DEFAULT_JWT_ALGORITHM = 'HS256';
56
- const DEFAULT_JWT_ISSUER = 'microservices-auth';
89
+ /**
90
+ * Action name constants used in runAction() for logging and access control.
91
+ * Match the operation names on BaseCore and BaseGateway.
92
+ */
57
93
  const ACTIONS = {
58
94
  LIST: 'LIST',
59
95
  GET: 'GET',
@@ -66,4 +102,48 @@ const ACTIONS = {
66
102
  REMOVE: 'REMOVE',
67
103
  REMOVE_MANY: 'REMOVE_MANY',
68
104
  };
105
+ /**
106
+ * ID type discriminator used by BaseCore.getIdType() to select the
107
+ * appropriate validator rule set in validateGet, validateGetMany,
108
+ * validateRemove, and validateRemoveMany.
109
+ */
110
+ var ID_TYPES;
111
+ (function (ID_TYPES) {
112
+ ID_TYPES[ID_TYPES["UNKNOWN"] = 0] = "UNKNOWN";
113
+ ID_TYPES[ID_TYPES["INT"] = 1] = "INT";
114
+ ID_TYPES[ID_TYPES["UUID"] = 2] = "UUID";
115
+ ID_TYPES[ID_TYPES["TEXT"] = 3] = "TEXT";
116
+ })(ID_TYPES || (ID_TYPES = {}));
117
+ /**
118
+ * Default primary key field name. Used by BaseGateway when idField
119
+ * is not explicitly set in config.
120
+ */
121
+ const ID_FIELD = FIELDS.ID;
122
+ /**
123
+ * Default starting orderNo value for new sequences.
124
+ * Stored as a string because it is used with StrOrderHelpers for
125
+ * lexicographic ordering. Converted to Number() for decimal ordering.
126
+ * The large value leaves room for manual insertions before the first
127
+ * auto-assigned record.
128
+ */
129
+ const DEFAULT_ORDER_NO = '10000000';
130
+ /**
131
+ * Default increment step for orderNo sequences.
132
+ * Stored as a string for the same reason as DEFAULT_ORDER_NO.
133
+ * Large step allows records to be manually inserted between auto-assigned
134
+ * values without requiring a full renumber.
135
+ */
136
+ const DEFAULT_ORDER_NO_STEP = '1000';
137
+ /**
138
+ * Default JWT signing algorithm.
139
+ * HS256 (HMAC-SHA256) — symmetric, suitable for single-service tokens.
140
+ * Override via verifyTokenArgs.algorithms for RS256 or other asymmetric algorithms.
141
+ */
142
+ const DEFAULT_JWT_ALGORITHM = 'HS256';
143
+ /**
144
+ * Default JWT issuer claim value.
145
+ * Verified during token validation in authenticate().
146
+ * Override via verifyTokenArgs.issuer for service-specific issuers.
147
+ */
148
+ const DEFAULT_JWT_ISSUER = 'microservices-auth';
69
149
  export { ID_FIELD, FIELDS, ORDER_BYS, HEADERS, DEFAULT_ORDER_NO, DEFAULT_ORDER_NO_STEP, ID_TYPES, DEFAULT_JWT_ALGORITHM, DEFAULT_JWT_ISSUER, ACTIONS, };
@@ -1,43 +1,103 @@
1
1
  /**
2
- * Removes all the records from provided table.
3
- * If appSettings has cleanTable object with table names then
4
- * it is used to add extra filters to clear the table to avoid for example users data
5
- * @param table Name of table from which to remove all the records
6
- * @param knexHandle Knex handle object with configured connection to DB
7
- * @param appSettings settings with db related information
2
+ * Validates that a database identifier (schema name, table name) contains
3
+ * only safe characters — alphanumeric and underscores.
4
+ * Throws if the identifier contains anything else to prevent SQL injection
5
+ * via template-interpolated schema names in SQLS above.
6
+ *
7
+ * @param identifier Schema or table name to validate
8
+ */
9
+ export declare const sanitiseIdentifier: (identifier: string | undefined) => string;
10
+ /**
11
+ * Guards that the provided dbType is supported by SQLS.
12
+ * Throws a clear error rather than letting the caller hit
13
+ * `TypeError: Cannot read properties of undefined`.
14
+ *
15
+ * @param dbType Database type string from appSettings
16
+ */
17
+ export declare const assertSupportedDbType: (dbType: string) => void;
18
+ /**
19
+ * Removes all records from the specified table.
20
+ *
21
+ * If `appSettings.cleanTableFilters[table]` is configured, applies additional
22
+ * WHERE conditions before deleting — useful for preserving seed/system records
23
+ * while clearing user-generated data during test teardown.
24
+ *
25
+ * @param table Name of the table to clean
26
+ * @param knexHandle Knex instance with configured DB connection
27
+ * @param appSettings Settings object with dbSchema and optional cleanTableFilters
8
28
  */
9
29
  declare const dbCleanTable: (table: string, knexHandle: any, appSettings: any) => Promise<void>;
10
30
  /**
11
- * Returns a list of tables in db schedm specified in settings
12
- * @param knexHandle Knex handle object with configured connection to DB
13
- * @param appSettings settings with db related information
14
- * @returns arrays of table names in the provided db schema
31
+ * Returns the list of table names in the configured schema.
32
+ * Tables listed in `appSettings.skipTables` are excluded from the result.
33
+ *
34
+ * Uses schema-scoped query when `appSettings.dbSchema` is set,
35
+ * otherwise queries all tables in the database.
36
+ *
37
+ * Handles both pg (result.rows array) and mssql (direct array) result formats.
38
+ *
39
+ * @param knexHandle Knex instance with configured DB connection
40
+ * @param appSettings Settings object with dbType, dbSchema, and optional skipTables
41
+ */
42
+ declare const dbListTables: (knexHandle: any, appSettings: any) => Promise<string[]>;
43
+ /**
44
+ * Deletes all records from the provided list of tables, one at a time.
45
+ * Order matters if foreign key constraints exist — pass tables in dependency order.
46
+ *
47
+ * @param tablesToClean Array of table names to clean
48
+ * @param knexHandle Knex instance with configured DB connection
49
+ * @param appSettings Settings object passed through to dbCleanTable
50
+ * @returns The list of cleaned table names
15
51
  */
16
- declare const dbListTables: (knexHandle: any, appSettings: any) => Promise<any>;
52
+ declare const dbClean: (tablesToClean: string[], knexHandle: any, appSettings: any) => Promise<string[]>;
17
53
  /**
18
- * Removes all the records from provided list of tables
19
- * @param tablesToClean array of table names
20
- * @param knexHandle Knex handle object with configured connection to DB
21
- * @param appSettings settings with db related information
22
- * @returns promise
54
+ * Drops all tables in the configured schema (or entire database if no schema set).
55
+ *
56
+ * WARNING: Destructive — permanently removes all tables and their data.
57
+ * Does not handle foreign key constraints — tables with dependencies may
58
+ * fail to drop. See TODO below.
59
+ *
60
+ * TODO: Remove all constraints before dropping tables to handle FK dependencies.
61
+ *
62
+ * @param knexHandle Knex instance with configured DB connection
63
+ * @param appSettings Settings object with dbType and optional dbSchema
23
64
  */
24
- declare const dbClean: (tablesToClean: any[], knexHandle: any, appSettings: any) => Promise<unknown>;
65
+ declare const dbWipe: (knexHandle: any, appSettings: any) => Promise<void>;
25
66
  /**
26
- * Selects all the tables in the schema and drops them.
27
- * This approach does not work in case we have constraints.
28
- * TODO: Remove all constraints and then drop tables.
67
+ * Drops all tables, runs all pending migrations, then optionally seeds the database.
68
+ * Intended for test environment reset between test suites.
69
+ *
70
+ * Fix: now re-throws after logging so callers know the reset failed rather
71
+ * than silently continuing with a broken database state.
72
+ *
73
+ * @param knexHandle Knex instance with configured DB connection
74
+ * @param appSettings Settings object passed through to dbWipe and dbRunMigrations
29
75
  */
30
- declare const dbWipe: (knexHandle: any, appSettings: any) => any;
76
+ declare const dbReset: (knexHandle: any, appSettings: any) => Promise<void>;
31
77
  /**
32
- * Drop all tables, run migrations, then seed
78
+ * Merges an array of seed result objects into a single flat object.
79
+ *
80
+ * Converts: `[{ table1: [...], table2: [...] }, { table3: [...] }]`
81
+ * Into: `{ table1: [...], table2: [...], table3: [...] }`
82
+ *
83
+ * Useful for collecting the results of multiple seed generators before
84
+ * inserting or asserting on them in tests.
85
+ *
86
+ * Fix: replaced `for...in` (which includes inherited properties) with
87
+ * `Object.assign()` which only copies own enumerable properties.
88
+ *
89
+ * @param generatedSeedArrays Array of seed result objects to merge
33
90
  */
34
- declare const dbReset: (knexHandle: any, appSettings: any) => any;
91
+ declare const dbTransformSeedsToObject: (generatedSeedArrays: any[]) => Record<string, any[]>;
35
92
  /**
36
- * Go from array of objects which contain keys of object names which have an array value of seeded objects
37
- * to a single object with keys of object names and arrays of seeded objects
38
- * ie from [{table1: [], table2: [] }, { table3: [] }]
39
- * to { table1: [], table2: [], table3: []}
93
+ * Runs all pending Knex migrations and optionally seeds the database.
94
+ * Seeds are only run if `appSettings.runDbSeed` is true AND at least one
95
+ * migration was applied — prevents re-seeding an already-seeded database.
96
+ *
97
+ * Logs the number of migrations run and the resulting schema version.
98
+ *
99
+ * @param knexHandle Knex instance with configured DB connection
100
+ * @param appSettings Settings object with optional runDbSeed flag
40
101
  */
41
- declare const dbTransformSeedsToObject: (generatedSeedArrays: any[]) => any;
42
- declare const dbRunMigrations: (knexHandle: any, appSettings: any) => any;
102
+ declare const dbRunMigrations: (knexHandle: any, appSettings: any) => Promise<void>;
43
103
  export { dbCleanTable, dbListTables, dbClean, dbWipe, dbReset, dbTransformSeedsToObject, dbRunMigrations };