lumen-framework 3.1.0 → 4.0.0

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 (258) hide show
  1. package/README.md +75 -109
  2. package/bin/lumen +23 -41
  3. package/dist/cli.cjs +856 -479
  4. package/dist/cli.cjs.map +4 -4
  5. package/dist/index.js +3284 -1720
  6. package/dist/index.js.map +4 -4
  7. package/dist/index.mjs +3263 -1699
  8. package/dist/index.mjs.map +4 -4
  9. package/dist/testing.js +280 -0
  10. package/dist/testing.js.map +7 -0
  11. package/dist/testing.mjs +252 -0
  12. package/dist/testing.mjs.map +7 -0
  13. package/dist/types/errors/links-only-error.d.ts +13 -0
  14. package/dist/types/errors/reserved-field-name-error.d.ts +13 -0
  15. package/dist/types/errors/unknown-attribute-error.d.ts +13 -0
  16. package/dist/types/index.d.ts +14 -0
  17. package/dist/types/interfaces.d.ts +1 -1
  18. package/dist/types/packages/application/index.d.ts +38 -45
  19. package/dist/types/packages/application/initialize.d.ts +3 -5
  20. package/dist/types/packages/application/interfaces.d.ts +13 -5
  21. package/dist/types/packages/application/utils/create-controller.d.ts +14 -4
  22. package/dist/types/packages/application/utils/create-serializer.d.ts +2 -2
  23. package/dist/types/packages/application/utils/normalize-port.d.ts +1 -3
  24. package/dist/types/packages/application/utils/resolve-visibility.d.ts +15 -0
  25. package/dist/types/packages/application/utils/restrict-open-namespaces.d.ts +19 -0
  26. package/dist/types/packages/application/utils/validate-attributes.d.ts +17 -0
  27. package/dist/types/packages/application/utils/validate-links-only.d.ts +19 -0
  28. package/dist/types/packages/application/utils/validate-namespaced-serializers.d.ts +3 -3
  29. package/dist/types/packages/application/utils/validate-reserved-names.d.ts +12 -0
  30. package/dist/types/packages/application/utils/warn-query-param-names.d.ts +10 -0
  31. package/dist/types/packages/cli/commands/dbcreate.d.ts +1 -1
  32. package/dist/types/packages/cli/commands/dbdrop.d.ts +1 -1
  33. package/dist/types/packages/cli/commands/destroy.d.ts +3 -2
  34. package/dist/types/packages/cli/commands/generate.d.ts +5 -5
  35. package/dist/types/packages/cli/commands/index.d.ts +0 -1
  36. package/dist/types/packages/cli/generator/index.d.ts +6 -6
  37. package/dist/types/packages/cli/generator/interfaces.d.ts +3 -3
  38. package/dist/types/packages/cli/generator/utils/create-generator.d.ts +2 -2
  39. package/dist/types/packages/cli/generator/utils/generate-type.d.ts +9 -9
  40. package/dist/types/packages/cli/generator/utils/migration-conflict.d.ts +4 -4
  41. package/dist/types/packages/cli/templates/pnpm-workspace.d.ts +15 -0
  42. package/dist/types/packages/cli/utils/create-spinner.d.ts +14 -0
  43. package/dist/types/packages/cli/utils/print-statements.d.ts +12 -0
  44. package/dist/types/packages/cli/utils/server-database.d.ts +27 -0
  45. package/dist/types/packages/compiler/interfaces.d.ts +1 -1
  46. package/dist/types/packages/config/interfaces.d.ts +10 -4
  47. package/dist/types/packages/controller/constants.d.ts +7 -2
  48. package/dist/types/packages/controller/errors/related-record-not-found-error.d.ts +4 -4
  49. package/dist/types/packages/controller/index.d.ts +364 -473
  50. package/dist/types/packages/controller/interfaces.d.ts +21 -6
  51. package/dist/types/packages/controller/utils/find-many.d.ts +2 -5
  52. package/dist/types/packages/controller/utils/find-one.d.ts +2 -5
  53. package/dist/types/packages/controller/utils/params-to-query.d.ts +8 -10
  54. package/dist/types/packages/controller/utils/resolve-relationships.d.ts +1 -3
  55. package/dist/types/packages/controller/utils/validate-relationships.d.ts +5 -3
  56. package/dist/types/packages/controller/visibility/errors.d.ts +21 -0
  57. package/dist/types/packages/controller/visibility/index.d.ts +51 -0
  58. package/dist/types/packages/database/attribute/index.d.ts +4 -6
  59. package/dist/types/packages/database/attribute/interfaces.d.ts +1 -1
  60. package/dist/types/packages/database/attribute/utils/create-attribute.d.ts +3 -5
  61. package/dist/types/packages/database/attribute/utils/create-getter.d.ts +2 -2
  62. package/dist/types/packages/database/attribute/utils/create-setter.d.ts +3 -5
  63. package/dist/types/packages/database/constants.d.ts +1 -0
  64. package/dist/types/packages/database/errors/index.d.ts +1 -0
  65. package/dist/types/packages/database/errors/invalid-driver-error.d.ts +1 -3
  66. package/dist/types/packages/database/errors/migrations-pending-error.d.ts +1 -3
  67. package/dist/types/packages/database/errors/model-missing-error.d.ts +1 -3
  68. package/dist/types/packages/database/errors/relationship-config-error.d.ts +10 -0
  69. package/dist/types/packages/database/errors/unique-constraint-error.d.ts +1 -1
  70. package/dist/types/packages/database/index.d.ts +9 -6
  71. package/dist/types/packages/database/initialize.d.ts +3 -5
  72. package/dist/types/packages/database/interfaces.d.ts +115 -25
  73. package/dist/types/packages/database/migration/index.d.ts +5 -7
  74. package/dist/types/packages/database/migration/interfaces.d.ts +2 -4
  75. package/dist/types/packages/database/migration/utils/generate-timestamp.d.ts +9 -1
  76. package/dist/types/packages/database/model/index.d.ts +348 -759
  77. package/dist/types/packages/database/model/initialize-class.d.ts +7 -1
  78. package/dist/types/packages/database/model/interfaces.d.ts +30 -12
  79. package/dist/types/packages/database/model/utils/attribute.d.ts +14 -0
  80. package/dist/types/packages/database/model/utils/get-columns.d.ts +1 -3
  81. package/dist/types/packages/database/model/utils/persistence.d.ts +5 -14
  82. package/dist/types/packages/database/model/utils/process-write-error.d.ts +2 -2
  83. package/dist/types/packages/database/model/utils/run-hooks.d.ts +7 -3
  84. package/dist/types/packages/database/model/utils/validate.d.ts +4 -1
  85. package/dist/types/packages/database/query/errors/record-not-found-error.d.ts +1 -1
  86. package/dist/types/packages/database/query/index.d.ts +179 -3
  87. package/dist/types/packages/database/query/runner/index.d.ts +1 -3
  88. package/dist/types/packages/database/query/runner/utils/build-results.d.ts +3 -4
  89. package/dist/types/packages/database/query/utils/format-select.d.ts +1 -3
  90. package/dist/types/packages/database/relationship/index.d.ts +7 -6
  91. package/dist/types/packages/database/relationship/interfaces.d.ts +16 -3
  92. package/dist/types/packages/database/relationship/utils/getters.d.ts +7 -13
  93. package/dist/types/packages/database/relationship/utils/inverse-setters.d.ts +5 -9
  94. package/dist/types/packages/database/relationship/utils/setters.d.ts +7 -13
  95. package/dist/types/packages/database/relationship/utils/unassociate.d.ts +1 -3
  96. package/dist/types/packages/database/relationship/utils/update-relationship.d.ts +6 -2
  97. package/dist/types/packages/database/transaction/index.d.ts +9 -10
  98. package/dist/types/packages/database/transaction/interfaces.d.ts +7 -1
  99. package/dist/types/packages/database/utils/connect.d.ts +16 -3
  100. package/dist/types/packages/database/utils/create-migrations.d.ts +1 -3
  101. package/dist/types/packages/database/utils/normalize-model-name.d.ts +1 -3
  102. package/dist/types/packages/database/utils/pending-migrations.d.ts +1 -3
  103. package/dist/types/packages/database/utils/primary-key-type.d.ts +10 -0
  104. package/dist/types/packages/database/utils/type-for-column.d.ts +3 -5
  105. package/dist/types/packages/database/utils/validate-relationships.d.ts +13 -0
  106. package/dist/types/packages/database/validation/errors/validation-error.d.ts +4 -4
  107. package/dist/types/packages/database/validation/index.d.ts +3 -5
  108. package/dist/types/packages/database/validation/interfaces.d.ts +1 -1
  109. package/dist/types/packages/freezeable/map/index.d.ts +1 -3
  110. package/dist/types/packages/freezeable/set/index.d.ts +1 -3
  111. package/dist/types/packages/freezeable/utils/freeze.d.ts +5 -15
  112. package/dist/types/packages/freezeable/utils/is-frozen.d.ts +1 -3
  113. package/dist/types/packages/fs/index.d.ts +7 -7
  114. package/dist/types/packages/fs/interfaces.d.ts +4 -4
  115. package/dist/types/packages/fs/utils/parse-path.d.ts +2 -2
  116. package/dist/types/packages/fs/watcher/interfaces.d.ts +1 -1
  117. package/dist/types/packages/jsonapi/errors/invalid-content-type-error.d.ts +3 -5
  118. package/dist/types/packages/jsonapi/errors/not-acceptable-error.d.ts +2 -4
  119. package/dist/types/packages/jsonapi/errors/unsupported-media-type-error.d.ts +2 -4
  120. package/dist/types/packages/jsonapi/index.d.ts +1 -1
  121. package/dist/types/packages/jsonapi/interfaces.d.ts +47 -36
  122. package/dist/types/packages/jsonapi/utils/has-media-type-params.d.ts +1 -1
  123. package/dist/types/packages/jsonapi/utils/is-jsonapi.d.ts +1 -1
  124. package/dist/types/packages/jsonapi/utils/media-type.d.ts +2 -2
  125. package/dist/types/packages/loader/builder/index.d.ts +3 -3
  126. package/dist/types/packages/loader/builder/interfaces.d.ts +7 -7
  127. package/dist/types/packages/loader/builder/utils/create-children-builder.d.ts +2 -2
  128. package/dist/types/packages/loader/builder/utils/create-parent-builder.d.ts +9 -2
  129. package/dist/types/packages/loader/builder/utils/sort-by-namespace.d.ts +2 -2
  130. package/dist/types/packages/loader/index.d.ts +1 -1
  131. package/dist/types/packages/loader/interfaces.d.ts +2 -2
  132. package/dist/types/packages/loader/resolver/index.d.ts +2 -2
  133. package/dist/types/packages/loader/resolver/utils/closest-ancestor.d.ts +2 -2
  134. package/dist/types/packages/loader/resolver/utils/closest-child.d.ts +2 -2
  135. package/dist/types/packages/logger/constants.d.ts +3 -3
  136. package/dist/types/packages/logger/errors/invalid-config-error.d.ts +5 -0
  137. package/dist/types/packages/logger/index.d.ts +65 -142
  138. package/dist/types/packages/logger/interfaces.d.ts +52 -10
  139. package/dist/types/packages/logger/request-logger/index.d.ts +3 -5
  140. package/dist/types/packages/logger/request-logger/interfaces.d.ts +5 -5
  141. package/dist/types/packages/logger/request-logger/templates.d.ts +5 -9
  142. package/dist/types/packages/logger/request-logger/utils/filter-params.d.ts +6 -1
  143. package/dist/types/packages/logger/request-logger/utils/log-json.d.ts +2 -4
  144. package/dist/types/packages/logger/request-logger/utils/log-text.d.ts +1 -3
  145. package/dist/types/packages/logger/request-logger/utils/params-for.d.ts +9 -0
  146. package/dist/types/packages/logger/utils/error-name.d.ts +7 -0
  147. package/dist/types/packages/logger/utils/line.d.ts +1 -3
  148. package/dist/types/packages/logger/writer/constants.d.ts +0 -1
  149. package/dist/types/packages/logger/writer/index.d.ts +6 -6
  150. package/dist/types/packages/logger/writer/interfaces.d.ts +2 -2
  151. package/dist/types/packages/logger/writer/utils/format-message.d.ts +2 -2
  152. package/dist/types/packages/lumenify/index.d.ts +20 -5
  153. package/dist/types/packages/lumenify/utils/create-response-proxy.d.ts +1 -1
  154. package/dist/types/packages/pm/cluster/index.d.ts +56 -7
  155. package/dist/types/packages/pm/cluster/interfaces.d.ts +2 -1
  156. package/dist/types/packages/pm/index.d.ts +2 -2
  157. package/dist/types/packages/router/definitions/context/index.d.ts +5 -7
  158. package/dist/types/packages/router/definitions/context/utils/create-definition-group.d.ts +3 -5
  159. package/dist/types/packages/router/definitions/context/utils/create-definition.d.ts +11 -6
  160. package/dist/types/packages/router/definitions/context/utils/normalize-resource-args.d.ts +4 -5
  161. package/dist/types/packages/router/definitions/index.d.ts +5 -9
  162. package/dist/types/packages/router/definitions/interfaces.d.ts +4 -4
  163. package/dist/types/packages/router/index.d.ts +23 -11
  164. package/dist/types/packages/router/interfaces.d.ts +4 -4
  165. package/dist/types/packages/router/namespace/index.d.ts +7 -9
  166. package/dist/types/packages/router/namespace/interfaces.d.ts +3 -3
  167. package/dist/types/packages/router/namespace/utils/normalize-name.d.ts +1 -3
  168. package/dist/types/packages/router/namespace/utils/normalize-path.d.ts +1 -3
  169. package/dist/types/packages/router/resource/index.d.ts +7 -8
  170. package/dist/types/packages/router/resource/interfaces.d.ts +12 -4
  171. package/dist/types/packages/router/resource/utils/normalize-only.d.ts +3 -5
  172. package/dist/types/packages/router/route/action/enhancers/resource.d.ts +1 -3
  173. package/dist/types/packages/router/route/action/enhancers/track-perf.d.ts +1 -3
  174. package/dist/types/packages/router/route/action/index.d.ts +7 -2
  175. package/dist/types/packages/router/route/action/interfaces.d.ts +4 -0
  176. package/dist/types/packages/router/route/action/utils/create-page-links.d.ts +21 -5
  177. package/dist/types/packages/router/route/action/utils/get-action-name.d.ts +1 -3
  178. package/dist/types/packages/router/route/action/utils/get-controller-name.d.ts +1 -3
  179. package/dist/types/packages/router/route/index.d.ts +13 -9
  180. package/dist/types/packages/router/route/interfaces.d.ts +7 -5
  181. package/dist/types/packages/router/route/params/errors/client-generated-id-error.d.ts +4 -4
  182. package/dist/types/packages/router/route/params/errors/forbidden-parameter-error.d.ts +4 -4
  183. package/dist/types/packages/router/route/params/errors/index.d.ts +1 -0
  184. package/dist/types/packages/router/route/params/errors/invalid-parameter-error.d.ts +4 -6
  185. package/dist/types/packages/router/route/params/errors/parameter-not-nullable-error.d.ts +4 -6
  186. package/dist/types/packages/router/route/params/errors/parameter-range-error.d.ts +9 -0
  187. package/dist/types/packages/router/route/params/errors/parameter-required-error.d.ts +4 -6
  188. package/dist/types/packages/router/route/params/errors/parameter-type-error.d.ts +4 -6
  189. package/dist/types/packages/router/route/params/errors/parameter-value-error.d.ts +4 -6
  190. package/dist/types/packages/router/route/params/errors/resource-mismatch-error.d.ts +4 -6
  191. package/dist/types/packages/router/route/params/index.d.ts +5 -9
  192. package/dist/types/packages/router/route/params/interfaces.d.ts +12 -8
  193. package/dist/types/packages/router/route/params/parameter/forbidden-parameter.d.ts +1 -1
  194. package/dist/types/packages/router/route/params/parameter/ignored-parameter.d.ts +14 -0
  195. package/dist/types/packages/router/route/params/parameter/index.d.ts +21 -5
  196. package/dist/types/packages/router/route/params/parameter/interfaces.d.ts +2 -2
  197. package/dist/types/packages/router/route/params/parameter/utils/validate-range.d.ts +3 -0
  198. package/dist/types/packages/router/route/params/parameter/utils/validate-value.d.ts +1 -3
  199. package/dist/types/packages/router/route/params/parameter-group/index.d.ts +3 -5
  200. package/dist/types/packages/router/route/params/parameter-group/utils/missing-params.d.ts +8 -0
  201. package/dist/types/packages/router/route/params/utils/get-data-params.d.ts +5 -1
  202. package/dist/types/packages/router/route/params/utils/get-default-collection-params.d.ts +1 -3
  203. package/dist/types/packages/router/route/params/utils/get-default-member-params.d.ts +5 -2
  204. package/dist/types/packages/router/route/params/utils/get-query-params.d.ts +3 -9
  205. package/dist/types/packages/router/route/params/utils/get-url-params.d.ts +1 -3
  206. package/dist/types/packages/router/route/params/utils/parse-column-value.d.ts +16 -0
  207. package/dist/types/packages/router/route/params/utils/validate-client-id.d.ts +1 -1
  208. package/dist/types/packages/router/route/params/utils/validate-resource-id.d.ts +1 -3
  209. package/dist/types/packages/router/route/params/utils/validate-type.d.ts +3 -5
  210. package/dist/types/packages/router/route/utils/get-dynamic-segments.d.ts +1 -3
  211. package/dist/types/packages/router/route/utils/get-static-path.d.ts +6 -2
  212. package/dist/types/packages/router/utils/create-replacer.d.ts +10 -2
  213. package/dist/types/packages/serializer/index.d.ts +243 -434
  214. package/dist/types/packages/serializer/interfaces.d.ts +19 -1
  215. package/dist/types/packages/serializer/utils/include-tree.d.ts +12 -3
  216. package/dist/types/packages/serializer/utils/load-linkage.d.ts +9 -3
  217. package/dist/types/packages/server/errors/error-list.d.ts +25 -0
  218. package/dist/types/packages/server/errors/method-not-allowed-error.d.ts +11 -0
  219. package/dist/types/packages/server/index.d.ts +9 -9
  220. package/dist/types/packages/server/interfaces.d.ts +59 -7
  221. package/dist/types/packages/server/request/constants.d.ts +2 -2
  222. package/dist/types/packages/server/request/index.d.ts +3 -5
  223. package/dist/types/packages/server/request/interfaces.d.ts +72 -8
  224. package/dist/types/packages/server/request/parser/errors/malformed-request-error.d.ts +3 -5
  225. package/dist/types/packages/server/request/parser/index.d.ts +6 -1
  226. package/dist/types/packages/server/request/parser/utils/format.d.ts +13 -11
  227. package/dist/types/packages/server/request/parser/utils/normalize-document.d.ts +13 -0
  228. package/dist/types/packages/server/request/parser/utils/parse-nested-object.d.ts +1 -3
  229. package/dist/types/packages/server/request/parser/utils/parse-read.d.ts +2 -4
  230. package/dist/types/packages/server/request/parser/utils/parse-write.d.ts +17 -1
  231. package/dist/types/packages/server/request/utils/get-domain.d.ts +1 -3
  232. package/dist/types/packages/server/responder/index.d.ts +1 -3
  233. package/dist/types/packages/server/responder/utils/content-type-for.d.ts +8 -0
  234. package/dist/types/packages/server/responder/utils/data-for.d.ts +3 -5
  235. package/dist/types/packages/server/responder/utils/normalize.d.ts +2 -3
  236. package/dist/types/packages/server/response/index.d.ts +3 -5
  237. package/dist/types/packages/server/response/interfaces.d.ts +14 -3
  238. package/dist/types/packages/server/utils/client-ip-for.d.ts +10 -0
  239. package/dist/types/packages/server/utils/create-server-error.d.ts +11 -3
  240. package/dist/types/packages/server/utils/request-id-for.d.ts +9 -0
  241. package/dist/types/packages/server/utils/set-cors-headers.d.ts +2 -2
  242. package/dist/types/packages/server/utils/source-for.d.ts +19 -3
  243. package/dist/types/packages/server/utils/status-for-error.d.ts +6 -0
  244. package/dist/types/packages/server/utils/validate-accept.d.ts +1 -1
  245. package/dist/types/packages/server/utils/validate-content-type.d.ts +8 -3
  246. package/dist/types/packages/testing/audit-visibility.d.ts +189 -0
  247. package/dist/types/packages/testing/index.d.ts +4 -0
  248. package/dist/types/packages/testing/start-app.d.ts +52 -0
  249. package/dist/types/packages/testing/utils/identifiers-in.d.ts +14 -0
  250. package/dist/types/testing.d.ts +9 -0
  251. package/dist/types/utils/chalk.d.ts +16 -0
  252. package/dist/types/utils/pick.d.ts +2 -2
  253. package/package.json +54 -26
  254. package/dist/types/packages/cli/commands/test.d.ts +0 -4
  255. package/dist/types/packages/logger/utils/sql.d.ts +0 -4
  256. package/dist/types/packages/router/route/params/parameter-group/utils/has-required-params.d.ts +0 -5
  257. package/dist/types/utils/create-query-string.d.ts +0 -6
  258. package/dist/types/utils/has-own-property.d.ts +0 -1
@@ -1,8 +1,14 @@
1
1
  import type Database from '../index';
2
2
  import type { ModelClass } from '../interfaces';
3
3
  /**
4
- * @private
4
+ * The foreign key of a `hasOne` or non-through `hasMany` that does not
5
+ * declare one: its inverse `belongsTo`'s, which may declare it, else
6
+ * `<inverse>_id`. Models initialize concurrently, so `related.belongsTo` is
7
+ * either still its declaration or already initialized; both carry a declared
8
+ * `foreignKey`, and the default is the same.
5
9
  */
10
+ export declare function inverseForeignKey(related: ModelClass, inverse: string): string;
11
+ /** @internal */
6
12
  export default function initializeClass<T extends ModelClass>({ store, table, model }: {
7
13
  store: Database;
8
14
  table: T['table'];
@@ -1,14 +1,32 @@
1
1
  import type Model from './index';
2
- export type Model$Hook = (instance: Model, trx: unknown) => Promise<unknown>;
3
- export interface Model$Hooks {
4
- readonly afterCreate?: Model$Hook;
5
- readonly afterDestroy?: Model$Hook;
6
- readonly afterSave?: Model$Hook;
7
- readonly afterUpdate?: Model$Hook;
8
- readonly afterValidation?: Model$Hook;
9
- readonly beforeCreate?: Model$Hook;
10
- readonly beforeDestroy?: Model$Hook;
11
- readonly beforeSave?: Model$Hook;
12
- readonly beforeUpdate?: Model$Hook;
13
- readonly beforeValidation?: Model$Hook;
2
+ /**
3
+ * A model lifecycle hook: called with the record and the write's
4
+ * transaction. See {@link Model.hooks}.
5
+ */
6
+ export type ModelHook = (instance: Model, trx: unknown) => Promise<unknown>;
7
+ /**
8
+ * The hooks a model declares in {@link Model.hooks}, by the point in a
9
+ * record's life they run at.
10
+ */
11
+ export interface ModelHooks {
12
+ /** After a record is inserted, in its transaction. */
13
+ readonly afterCreate?: ModelHook;
14
+ /** After a record is deleted, in its transaction. */
15
+ readonly afterDestroy?: ModelHook;
16
+ /** After a record is inserted or updated; last. */
17
+ readonly afterSave?: ModelHook;
18
+ /** After a record is updated, in its transaction. */
19
+ readonly afterUpdate?: ModelHook;
20
+ /** After the record's validations pass. */
21
+ readonly afterValidation?: ModelHook;
22
+ /** Before a record is inserted, after validation. */
23
+ readonly beforeCreate?: ModelHook;
24
+ /** Before a record is deleted. */
25
+ readonly beforeDestroy?: ModelHook;
26
+ /** Before a record is inserted or updated; last before the write. */
27
+ readonly beforeSave?: ModelHook;
28
+ /** Before a record is updated, after validation. */
29
+ readonly beforeUpdate?: ModelHook;
30
+ /** Before the record's validations run, on create and update. */
31
+ readonly beforeValidation?: ModelHook;
14
32
  }
@@ -0,0 +1,14 @@
1
+ import type Model from '../index';
2
+ /**
3
+ * Read an attribute (or relationship) of `record` by name.
4
+ *
5
+ * @internal
6
+ */
7
+ export declare function readAttribute(record: Model, key: string): unknown;
8
+ /**
9
+ * Write an attribute (or relationship) of `record` by name. Unlike
10
+ * `Reflect.set`, a failed write throws rather than returning `false`.
11
+ *
12
+ * @internal
13
+ */
14
+ export declare function writeAttribute(record: Model, key: string, value: unknown): void;
@@ -1,5 +1,3 @@
1
1
  import type Model from '../index';
2
- /**
3
- * @private
4
- */
2
+ /** @internal */
5
3
  export default function getColumns(record: Model, only?: Array<string>): Record<string, unknown>;
@@ -1,18 +1,9 @@
1
- import type Logger from '../../../logger';
2
1
  import type Model from '../index';
3
- /**
4
- * @private
5
- */
2
+ /** @internal */
6
3
  export declare function create(record: Model, trx: unknown): Array<any>;
7
- /**
8
- * @private
9
- */
4
+ /** @internal */
10
5
  export declare function update(record: Model, trx: unknown): Array<any>;
11
- /**
12
- * @private
13
- */
6
+ /** @internal */
14
7
  export declare function destroy(record: Model, trx: unknown): Array<any>;
15
- /**
16
- * @private
17
- */
18
- export declare function createRunner(logger: Logger, statements: Array<any>): (query: Array<any>) => Promise<Array<any>>;
8
+ /** @internal */
9
+ export declare function createRunner({ logger, store }: Pick<typeof Model, 'logger' | 'store'>, statements: Array<any>): (query: Array<any>) => Promise<Array<any>>;
@@ -1,12 +1,12 @@
1
1
  /**
2
2
  * Map a database write error to the server error it should surface as.
3
3
  *
4
- * @private
4
+ * @internal
5
5
  */
6
6
  export default function processWriteError(err: unknown): unknown;
7
7
  /**
8
8
  * `.catch()` handler for a write: rethrows the mapped error.
9
9
  *
10
- * @private
10
+ * @internal
11
11
  */
12
12
  export declare function rethrowWriteError(err: unknown): never;
@@ -1,6 +1,10 @@
1
1
  import type Model from '../index';
2
- import type { Model$Hook } from '../interfaces';
2
+ import type { ModelHook } from '../interfaces';
3
3
  /**
4
- * @private
4
+ * Run `hooks` in order. Each receives the record bound to the write's
5
+ * transaction — so its relationship reads, `update`, `save` and `reload` join
6
+ * it — and the transaction itself, for queries on other models.
7
+ *
8
+ * @internal
5
9
  */
6
- export default function runHooks(record: Model, trx: unknown, ...hooks: Array<Model$Hook | undefined>): Promise<unknown>;
10
+ export default function runHooks(target: Model, trx: unknown, ...hooks: Array<ModelHook | undefined>): Promise<unknown>;
@@ -1,5 +1,8 @@
1
1
  import type { Model } from '../../index';
2
2
  /**
3
- * @private
3
+ * Run the model's validators over its dirty attributes. Every attribute that
4
+ * fails is reported (one 422 error object each), not just the first.
5
+ *
6
+ * @internal
4
7
  */
5
8
  export default function validate(instance: Model): true;
@@ -2,5 +2,5 @@ import type { ModelClass } from '../../interfaces';
2
2
  declare class RecordNotFoundError extends Error {
3
3
  constructor({ name, primaryKey }: ModelClass, primaryKeyValue: unknown);
4
4
  }
5
- declare const _default: new (...args: Array<any>) => RecordNotFoundError & import("../../../server/interfaces").Server$Error;
5
+ declare const _default: new (...args: Array<any>) => RecordNotFoundError & import("../../../server").ServerError;
6
6
  export default _default;
@@ -1,38 +1,214 @@
1
1
  import type { ModelClass } from '../interfaces';
2
2
  /**
3
- * @class Query
4
- * @extends Promise
5
- * @private
3
+ * The snapshots that narrow which rows match — the only ones `count()` keeps.
4
+ * Every condition the query builder can push belongs here: dropping one makes
5
+ * the count (and so the index action's page links) disagree with the rows.
6
+ *
7
+ * @internal
8
+ */
9
+ declare const CONDITIONS: Set<string>;
10
+ /**
11
+ * A lazily built database query. `Model.all()`, `Model.where()`,
12
+ * `Model.find()` and the other static query methods start one; chain more
13
+ * methods, and the model's scopes, onto it, and `await` it to run it:
14
+ *
15
+ * ```javascript
16
+ * const posts = await Post.where({ isPublic: true })
17
+ * .order('createdAt', 'DESC')
18
+ * .include('user')
19
+ * .page(2);
20
+ * ```
21
+ *
22
+ * A query resolves with an array of records, or with one record after
23
+ * {@link Query.find}, {@link Query.first} or {@link Query.last}, or with a
24
+ * number after {@link Query.count}. A controller action may return a query
25
+ * without awaiting it; Lumen runs it and serializes the result.
6
26
  */
7
27
  declare class Query<T = any> extends Promise<T> {
28
+ /** @internal */
8
29
  model: ModelClass;
30
+ /** @internal */
9
31
  isFind: boolean;
32
+ /** @internal */
10
33
  snapshots: Array<Array<any>>;
34
+ /** @internal */
11
35
  collection: boolean;
36
+ /** @internal */
12
37
  shouldCount: boolean;
38
+ /** @internal */
13
39
  relationships: Record<string, any>;
40
+ /** @internal */
41
+ trx: unknown;
14
42
  constructor(model: ModelClass);
15
43
  static get [Symbol.species](): PromiseConstructor;
44
+ /**
45
+ * Run the query — and the queries that load its included relationships —
46
+ * in the transaction `trx`, so it sees the rows the transaction has written
47
+ * and does not wait for another connection while the transaction holds
48
+ * one. Model hooks receive the write's transaction for this:
49
+ *
50
+ * ```javascript
51
+ * static hooks = {
52
+ * async afterCreate(comment, trx) {
53
+ * const post = await Post.transacting(trx).find(comment.postId);
54
+ * // …
55
+ * }
56
+ * };
57
+ * ```
58
+ *
59
+ * `Model.transacting(trx)` starts a query that is already bound, as above;
60
+ * this method binds one built another way.
61
+ */
62
+ transacting(trx: unknown): this;
63
+ /**
64
+ * Every record: adds no condition. `Model.all()` reads better than a bare
65
+ * query.
66
+ */
16
67
  all(): this;
68
+ /**
69
+ * The records that do *not* match `conditions`; the opposite of
70
+ * {@link Query.where}, with the same conditions.
71
+ *
72
+ * ```javascript
73
+ * await User.not({ name: 'Bob' });
74
+ * await User.not({ deletedAt: null }); // deleted_at IS NOT NULL
75
+ * ```
76
+ */
17
77
  not(conditions?: Record<string, any>): this;
78
+ /**
79
+ * The record with primary key `primaryKey`. The query resolves with the
80
+ * record, or rejects with a `RecordNotFoundError` — a `404` through the API —
81
+ * if there is none.
82
+ *
83
+ * ```javascript
84
+ * const post = await Post.find(1);
85
+ * ```
86
+ */
18
87
  find(primaryKey: any): this;
88
+ /**
89
+ * Page `num` of the records, counting from 1. The page size is the query's
90
+ * {@link Query.limit}, or 25.
91
+ *
92
+ * ```javascript
93
+ * await Post.order('createdAt', 'DESC').limit(10).page(2); // records 11–20
94
+ * ```
95
+ */
19
96
  page(num?: number): this;
97
+ /**
98
+ * At most `amount` records.
99
+ */
20
100
  limit(amount?: number): this;
101
+ /**
102
+ * Sort by the attribute `attr`, `'ASC'` (the default) or `'DESC'`. Ties are
103
+ * broken by the primary key, so pages are stable. A later `order` replaces an
104
+ * earlier one; an attribute the model doesn't have is ignored.
105
+ *
106
+ * ```javascript
107
+ * await Post.order('createdAt', 'DESC');
108
+ * ```
109
+ */
21
110
  order(attr: string, direction?: string): this;
111
+ /**
112
+ * The records matching every condition in `conditions`, an object of
113
+ * attribute names (camelCase, as on records) and values:
114
+ *
115
+ * ```javascript
116
+ * await Post.where({ userId: 1, isPublic: true });
117
+ * await Post.where({ id: [1, 2, 3] }); // any of: id IN (1, 2, 3)
118
+ * await Post.where({ publishedAt: null }); // published_at IS NULL
119
+ * ```
120
+ *
121
+ * Names that aren't attributes of the model are ignored. Calls chain as
122
+ * `AND`.
123
+ *
124
+ * @param not - Used by {@link Query.not}.
125
+ */
22
126
  where(conditions?: Record<string, any>, not?: boolean): this;
127
+ /**
128
+ * The records whose attributes lie within ranges, inclusive:
129
+ *
130
+ * ```javascript
131
+ * await Post.whereBetween({ createdAt: [lastWeek, now] });
132
+ * ```
133
+ *
134
+ * @param not - `true` for the records *outside* the ranges.
135
+ */
23
136
  whereBetween(conditions: Record<string, any>, not?: boolean): this;
137
+ /**
138
+ * The records matching a raw SQL condition, with `?` placeholders for
139
+ * `bindings`. Columns are snake_case here, as in the database:
140
+ *
141
+ * ```javascript
142
+ * await Post.whereRaw('lower(title) LIKE ?', ['%lumen%']);
143
+ * ```
144
+ *
145
+ * Never build `query` from user input; pass values as `bindings`.
146
+ */
24
147
  whereRaw(query: string, bindings?: Array<any>): this;
148
+ /**
149
+ * Only the first record — by primary key, or by the query's
150
+ * {@link Query.order} — instead of an array. Resolves with `undefined` when
151
+ * nothing matches.
152
+ */
25
153
  first(): this;
154
+ /**
155
+ * Only the last record — by primary key, or by the query's
156
+ * {@link Query.order} — instead of an array. Resolves with `undefined` when
157
+ * nothing matches.
158
+ */
26
159
  last(): this;
160
+ /**
161
+ * The number of matching records, instead of the records. Only the query's
162
+ * conditions count; `limit`, `page`, `order` and `include` are ignored.
163
+ *
164
+ * ```javascript
165
+ * const total = await Post.where({ isPublic: true }).count();
166
+ * ```
167
+ */
27
168
  count(): Query<number>;
169
+ /**
170
+ * Skip the first `amount` records.
171
+ */
28
172
  offset(amount: number): this;
173
+ /**
174
+ * Load only these attributes. Include the primary key when you will use
175
+ * the records for more than reading these values.
176
+ *
177
+ * ```javascript
178
+ * await User.select('id', 'name');
179
+ * ```
180
+ */
29
181
  select(...attrs: Array<string>): this;
182
+ /**
183
+ * Only unique combinations of these attributes.
184
+ */
30
185
  distinct(...attrs: Array<string>): this;
186
+ /**
187
+ * Load these relationships with the records, so reading them doesn't cost
188
+ * a query per record:
189
+ *
190
+ * ```javascript
191
+ * const posts = await Post.where({ isPublic: true }).include('user', 'tags');
192
+ * ```
193
+ *
194
+ * Pass an object to load only some attributes of each:
195
+ * `include({ user: ['name'] })`.
196
+ */
31
197
  include(...relationships: Array<Record<string, any> | string>): this;
198
+ /**
199
+ * Remove scopes from the query — by name, or every scope when called
200
+ * without arguments. `'order'` removes the sort order.
201
+ *
202
+ * ```javascript
203
+ * await Post.isPublic().unscope('isPublic');
204
+ * ```
205
+ */
32
206
  unscope(...scopes: Array<string>): this;
33
207
  then<TResult1 = T, TResult2 = never>(onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onRejected?: ((error: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
34
208
  catch<TResult = never>(onRejected?: ((error: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
209
+ /** @internal */
35
210
  static from(src: any): Query<unknown>;
36
211
  }
37
212
  export default Query;
38
213
  export { RecordNotFoundError } from './errors';
214
+ export { CONDITIONS };
@@ -1,7 +1,5 @@
1
1
  import type Query from '../index';
2
- /**
3
- * @private
4
- */
2
+ /** @internal */
5
3
  export declare function createRunner(target: Query<unknown>, opts: {
6
4
  resolve?: (value: any) => void;
7
5
  reject?: (error: Error) => void;
@@ -1,10 +1,9 @@
1
1
  import type Model from '../../../model';
2
2
  import type { ModelClass } from '../../../interfaces';
3
- /**
4
- * @private
5
- */
6
- export default function buildResults<T extends Model>({ model, records, relationships }: {
3
+ /** @internal */
4
+ export default function buildResults<T extends Model>({ model, records, relationships, trx }: {
7
5
  model: ModelClass<T>;
8
6
  records: Promise<Array<Record<string, any>>>;
9
7
  relationships: Record<string, any>;
8
+ trx?: unknown;
10
9
  }): Promise<Array<T>>;
@@ -1,5 +1,3 @@
1
1
  import type { ModelClass } from '../../interfaces';
2
- /**
3
- * @private
4
- */
2
+ /** @internal */
5
3
  export default function formatSelect(model: ModelClass, attrs?: Array<string>, prefix?: string): string[];
@@ -1,11 +1,12 @@
1
1
  import type Model from '../model';
2
- /**
3
- * @private
4
- */
2
+ /** @internal */
5
3
  export declare function set(owner: Model, key: string, value?: Array<Model> | Model | null): void;
6
4
  /**
7
- * @private
5
+ * The value of `owner`'s relationship `key`: the loaded or assigned one, or
6
+ * else read from the database — in `trx` when given.
7
+ *
8
+ * @internal
8
9
  */
9
- export declare function get(owner: Model, key: string): Promise<Array<Model> | Model | null>;
10
+ export declare function get(owner: Model, key: string, trx?: unknown): Promise<Array<Model> | Model | null>;
10
11
  export { default as updateRelationship } from './utils/update-relationship';
11
- export type { Relationship$opts } from './interfaces';
12
+ export type { RelationshipOptions } from './interfaces';
@@ -1,12 +1,25 @@
1
1
  import type { Model } from '../index';
2
2
  import type { ModelClass } from '../interfaces';
3
- type Relationship$ref = Model | Array<Model>;
4
- export type Relationship$refs = WeakMap<Model, Map<string, Relationship$ref>>;
5
- export type Relationship$opts = {
3
+ type RelationshipRef = Model | Array<Model>;
4
+ export type RelationshipRefs = WeakMap<Model, Map<string, RelationshipRef>>;
5
+ /**
6
+ * A relationship as Lumen resolves it when the app boots, from a model's
7
+ * {@link Model.hasOne}, {@link Model.hasMany} or {@link Model.belongsTo}
8
+ * declaration.
9
+ */
10
+ export type RelationshipOptions = {
11
+ /** Which kind of relationship it is. */
6
12
  type: 'hasOne' | 'hasMany' | 'belongsTo';
13
+ /** The related model. */
7
14
  model: ModelClass;
15
+ /** The name of the relationship on the related model that points back. */
8
16
  inverse: string;
17
+ /** The join model of a many-to-many relationship. */
9
18
  through?: ModelClass;
19
+ /**
20
+ * The foreign key column: the declared `foreignKey`, or one derived from
21
+ * the relationship's names.
22
+ */
10
23
  foreignKey: string;
11
24
  };
12
25
  export {};
@@ -1,14 +1,8 @@
1
1
  import type Model from '../../model';
2
- import type { Relationship$opts } from '../index';
3
- /**
4
- * @private
5
- */
6
- export declare function getHasOne(owner: Model, { model, foreignKey }: Relationship$opts): import("../..").Query<Model>;
7
- /**
8
- * @private
9
- */
10
- export declare function getHasMany(owner: Model, opts: Relationship$opts): Promise<Model[]>;
11
- /**
12
- * @private
13
- */
14
- export declare function getBelongsTo(owner: Model, { model, foreignKey }: Relationship$opts): import("../..").Query<Model> | Promise<null>;
2
+ import type { RelationshipOptions } from '../index';
3
+ /** @internal */
4
+ export declare function getHasOne(owner: Model, { model, foreignKey }: RelationshipOptions, trx?: unknown): import("../..").Query<Model>;
5
+ /** @internal */
6
+ export declare function getHasMany(owner: Model, opts: RelationshipOptions, trx?: unknown): Promise<Model[]>;
7
+ /** @internal */
8
+ export declare function getBelongsTo(owner: Model, { model, foreignKey }: RelationshipOptions, trx?: unknown): import("../..").Query<Model> | Promise<null>;
@@ -1,15 +1,11 @@
1
1
  import type Model from '../../model';
2
2
  import type { ModelClass } from '../../interfaces';
3
- import type { Relationship$opts } from '../index';
4
- /**
5
- * @private
6
- */
7
- export declare function setHasManyInverse(owner: Model, value: Array<Model>, { inverse, foreignKey, inverseModel }: Relationship$opts & {
3
+ import type { RelationshipOptions } from '../index';
4
+ /** @internal */
5
+ export declare function setHasManyInverse(owner: Model, value: Array<Model>, { inverse, foreignKey, inverseModel }: RelationshipOptions & {
8
6
  inverseModel: ModelClass;
9
7
  }): void;
10
- /**
11
- * @private
12
- */
13
- export declare function setHasOneInverse(owner: Model, value: Model | null | undefined, { inverse, foreignKey, inverseModel }: Relationship$opts & {
8
+ /** @internal */
9
+ export declare function setHasOneInverse(owner: Model, value: Model | null | undefined, { inverse, foreignKey, inverseModel }: RelationshipOptions & {
14
10
  inverseModel: ModelClass;
15
11
  }): void;
@@ -1,14 +1,8 @@
1
1
  import type Model from '../../model';
2
- import type { Relationship$opts } from '../index';
3
- /**
4
- * @private
5
- */
6
- export declare function setHasMany(owner: Model, key: string, value: Array<Model>, { type, model, inverse, foreignKey }: Relationship$opts): void;
7
- /**
8
- * @private
9
- */
10
- export declare function setHasOne(owner: Model, key: string, value: Model | null | undefined, { type, model, inverse, foreignKey }: Relationship$opts): void;
11
- /**
12
- * @private
13
- */
14
- export declare function setBelongsTo(owner: Model, key: string, value: Model | null | undefined, { type, model, inverse, foreignKey }: Relationship$opts): void;
2
+ import type { RelationshipOptions } from '../index';
3
+ /** @internal */
4
+ export declare function setHasMany(owner: Model, key: string, value: Array<Model>, { type, model, inverse, foreignKey }: RelationshipOptions): void;
5
+ /** @internal */
6
+ export declare function setHasOne(owner: Model, key: string, value: Model | null | undefined, { type, model, inverse, foreignKey }: RelationshipOptions): void;
7
+ /** @internal */
8
+ export declare function setBelongsTo(owner: Model, key: string, value: Model | null | undefined, { type, model, inverse, foreignKey }: RelationshipOptions): void;
@@ -1,5 +1,3 @@
1
1
  import type Model from '../../model';
2
- /**
3
- * @private
4
- */
2
+ /** @internal */
5
3
  export default function unassociate<T extends Model>(value: Array<T>, foreignKey: string): Array<T>;
@@ -1,5 +1,9 @@
1
1
  import type Model from '../../model';
2
2
  /**
3
- * @private
3
+ * The statements that persist the relationship `name` of `record`, if it
4
+ * changed. A has-many-through relationship is written to its join table
5
+ * before this resolves, and contributes no statements.
6
+ *
7
+ * @internal
4
8
  */
5
- export default function updateRelationship(record: Model, name: string, trx: unknown): Array<unknown>;
9
+ export default function updateRelationship(record: Model, name: string, trx: unknown): Promise<Array<unknown>>;
@@ -1,16 +1,15 @@
1
1
  import type { Model } from '../index';
2
2
  import type { ModelClass } from '../interfaces';
3
- import type { Transaction$ResultProxy } from './interfaces';
3
+ import type { TransactionResult } from './interfaces';
4
4
  /**
5
- * @private
5
+ * `target` with `create` writing in `trx`, and every static that starts a
6
+ * query (`find`, `where`, `first`, a scope, …) returning one that runs in it.
7
+ *
8
+ * @internal
6
9
  */
7
10
  export declare function createStaticTransactionProxy<T extends ModelClass>(target: T, trx: unknown): T;
8
- /**
9
- * @private
10
- */
11
+ /** @internal */
11
12
  export declare function createInstanceTransactionProxy<T extends Model>(target: T, trx: unknown): T;
12
- /**
13
- * @private
14
- */
15
- export declare function createTransactionResultProxy<T extends Model, U extends boolean>(record: T, didPersist: U): Transaction$ResultProxy<T, U>;
16
- export type { Transaction$ResultProxy } from './interfaces';
13
+ /** @internal */
14
+ export declare function createTransactionResultProxy<T extends Model, U extends boolean>(record: T, didPersist: U): TransactionResult<T, U>;
15
+ export type { TransactionResult } from './interfaces';
@@ -1,5 +1,11 @@
1
1
  import type { Model } from '../index';
2
- export type Transaction$ResultProxy<T extends Model, U extends boolean> = T & {
2
+ /**
3
+ * What a write (`create`, `update`, `save`, `destroy`) resolves with: the
4
+ * record, with two extra members.
5
+ */
6
+ export type TransactionResult<T extends Model, U extends boolean> = T & {
7
+ /** Whether the write changed anything in the database. */
3
8
  didPersist: U;
9
+ /** The record itself, without these members. */
4
10
  unwrap(): T;
5
11
  };
@@ -1,6 +1,19 @@
1
1
  import type { Knex } from 'knex';
2
- import type { Database$environment } from '../interfaces';
2
+ import type { DatabaseEnvironmentConfig } from '../interfaces';
3
3
  /**
4
- * @private
4
+ * The knex `connection` for an environment's database config.
5
+ *
6
+ * A URL — `DATABASE_URL`, else the environment's `url` — gives the host,
7
+ * credentials and database, and replaces those settings. `ssl` from the
8
+ * config still applies on top of it (for `pg` and `mysql2`, which take the
9
+ * URL as `connectionString` / `uri` next to their other options), so an app
10
+ * on a platform that sets `DATABASE_URL` can configure TLS in
11
+ * `config/database.js`. A TLS setting written in the URL itself
12
+ * (`?sslmode=…` for `pg`, `?ssl=…` for `mysql2`) takes precedence: the
13
+ * drivers apply what they parse from the URL last.
14
+ *
15
+ * @internal
5
16
  */
6
- export default function connect(path: string, config: Database$environment): Knex;
17
+ export declare function connectionFor(path: string, config: DatabaseEnvironmentConfig, databaseUrl?: string | undefined): string | Record<string, unknown>;
18
+ /** @internal */
19
+ export default function connect(path: string, config: DatabaseEnvironmentConfig): Knex;
@@ -1,5 +1,3 @@
1
1
  import type Database from '../index';
2
- /**
3
- * @private
4
- */
2
+ /** @internal */
5
3
  export default function createMigrations(schema: Database['schema']): Promise<boolean>;
@@ -1,5 +1,3 @@
1
- /**
2
- * @private
3
- */
1
+ /** @internal */
4
2
  declare const _default: (input: unknown) => string;
5
3
  export default _default;
@@ -1,4 +1,2 @@
1
- /**
2
- * @private
3
- */
1
+ /** @internal */
4
2
  export default function pendingMigrations(appPath: string, table: () => any): Promise<Array<string>>;
@@ -0,0 +1,10 @@
1
+ import type { ModelClass } from '../interfaces';
2
+ /**
3
+ * The type of `model`'s primary key column: `'number'` for an auto-increment
4
+ * id, `'string'` for e.g. a uuid or `varchar` (PostgreSQL reports the latter
5
+ * as `character varying`, which `typeForColumn` does not know). `'number'`
6
+ * when the column is unknown.
7
+ *
8
+ * @internal
9
+ */
10
+ export default function primaryKeyType(model: ModelClass): string;