@terreno/api 0.29.0 → 0.30.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 (45) hide show
  1. package/CHANGELOG.md +79 -0
  2. package/dist/actions.js +17 -8
  3. package/dist/actions.test.js +8 -3
  4. package/dist/api.arrayOperations.test.js +16 -8
  5. package/dist/api.coverage.test.js +2 -1
  6. package/dist/api.errorPaths.test.js +522 -1
  7. package/dist/api.errors.test.js +9 -0
  8. package/dist/api.js +137 -170
  9. package/dist/api.query.test.js +20 -8
  10. package/dist/api.test.js +12 -6
  11. package/dist/auth.coverage.test.d.ts +1 -0
  12. package/dist/auth.coverage.test.js +202 -0
  13. package/dist/auth.test.js +159 -0
  14. package/dist/docLoader.js +5 -1
  15. package/dist/envConfigurationPlugin.d.ts +1 -1
  16. package/dist/envConfigurationPlugin.js +0 -2
  17. package/dist/errors.d.ts +14 -0
  18. package/dist/errors.js +24 -2
  19. package/dist/errors.test.js +137 -0
  20. package/dist/httpClient.js +5 -1
  21. package/dist/plugins.d.ts +4 -4
  22. package/dist/plugins.js +51 -9
  23. package/dist/plugins.test.js +61 -17
  24. package/dist/realtime/registry.d.ts +3 -2
  25. package/package.json +2 -2
  26. package/src/actions.test.ts +8 -3
  27. package/src/actions.ts +19 -10
  28. package/src/api.arrayOperations.test.ts +16 -8
  29. package/src/api.coverage.test.ts +2 -1
  30. package/src/api.errorPaths.test.ts +313 -3
  31. package/src/api.errors.test.ts +12 -0
  32. package/src/api.query.test.ts +20 -8
  33. package/src/api.test.ts +12 -6
  34. package/src/api.ts +141 -161
  35. package/src/auth.coverage.test.ts +101 -0
  36. package/src/auth.test.ts +125 -2
  37. package/src/docLoader.ts +6 -2
  38. package/src/envConfigurationPlugin.ts +2 -6
  39. package/src/errors.test.ts +106 -1
  40. package/src/errors.ts +25 -1
  41. package/src/httpClient.ts +6 -2
  42. package/src/plugins.test.ts +45 -9
  43. package/src/plugins.ts +72 -35
  44. package/src/realtime/changeStreamWatcher.ts +8 -1
  45. package/src/realtime/registry.ts +3 -4
package/src/api.ts CHANGED
@@ -18,10 +18,15 @@ import {
18
18
  import {authenticateMiddleware, type User} from "./auth";
19
19
  import {
20
20
  APIError,
21
+ type APIErrorOptions,
21
22
  apiErrorMiddleware,
22
- errorMessage,
23
+ BadRequestError,
24
+ errorDetail,
25
+ ForbiddenError,
23
26
  getDisableExternalErrorTracking,
24
27
  isAPIError,
28
+ mongooseErrorToAPIError,
29
+ NotFoundError,
25
30
  } from "./errors";
26
31
  import {logger} from "./logger";
27
32
  import {
@@ -56,6 +61,39 @@ export interface JSONObject {
56
61
  }
57
62
  export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
58
63
 
64
+ /**
65
+ * Picks the error to throw for something caught in a hook, transformer, or Mongoose middleware.
66
+ * An `APIError` is passed through untouched so its status, code, detail, and meta reach the client;
67
+ * anything else is wrapped in the given framework error. `wrapper` may override any field,
68
+ * including `detail`, which defaults to the caught error's text.
69
+ */
70
+ const passthroughOrWrap = (error: unknown, wrapper: APIErrorOptions): APIError => {
71
+ if (isAPIError(error)) {
72
+ return error;
73
+ }
74
+ return new APIError({
75
+ cause: error,
76
+ detail: errorDetail(error),
77
+ disableExternalErrorTracking: getDisableExternalErrorTracking(error),
78
+ ...wrapper,
79
+ });
80
+ };
81
+
82
+ /**
83
+ * `passthroughOrWrap` for write paths (`model.create`, `doc.save`). Mongoose validation and cast
84
+ * errors are converted first so their per-field messages survive as `meta.fields` instead of being
85
+ * flattened into the wrapper's `detail`.
86
+ */
87
+ const passthroughOrWrapWrite = (error: unknown, wrapper: APIErrorOptions): APIError => {
88
+ if (!isAPIError(error) && error instanceof Error) {
89
+ const converted = mongooseErrorToAPIError(error);
90
+ if (converted) {
91
+ return converted;
92
+ }
93
+ }
94
+ return passthroughOrWrap(error, wrapper);
95
+ };
96
+
59
97
  export const addPopulateToQuery = (
60
98
  // noExplicitAny: mongoose Query type parameters vary widely across populated/unpopulated documents — caller passes concrete types
61
99
  // biome-ignore lint/suspicious/noExplicitAny: mongoose Query type parameters vary widely across populated/unpopulated documents — caller passes concrete types
@@ -350,9 +388,11 @@ export interface ModelRouterOptions<T> {
350
388
  const parseDateRangeBound = (rawValue: unknown, queryKey: string): Date => {
351
389
  const parsed = DateTime.fromISO(String(rawValue), {zone: "utc"});
352
390
  if (!parsed.isValid) {
353
- throw new APIError({
354
- status: 400,
355
- title: `Invalid date for query parameter ${queryKey}`,
391
+ throw new BadRequestError({
392
+ code: "invalid-date-query-parameter",
393
+ detail: `Invalid date for query parameter ${queryKey}`,
394
+ source: {parameter: queryKey},
395
+ title: "Invalid date query parameter",
356
396
  });
357
397
  }
358
398
  return parsed.toJSDate();
@@ -431,9 +471,11 @@ const checkQueryParamAllowed = (
431
471
  return;
432
472
  }
433
473
  if (!queryFields.includes(queryParam)) {
434
- throw new APIError({
435
- status: 400,
436
- title: `${queryParam} is not allowed as a query param.`,
474
+ throw new BadRequestError({
475
+ code: "query-param-not-allowed",
476
+ detail: `${queryParam} is not allowed as a query param.`,
477
+ source: {parameter: queryParam},
478
+ title: "Query parameter not allowed",
437
479
  });
438
480
  }
439
481
  };
@@ -596,7 +638,7 @@ export function modelRouter<T>(
596
638
  collectionName: model.collection.collectionName,
597
639
  config: options.realtime,
598
640
  modelName: model.modelName,
599
- options,
641
+ options: options as unknown as ModelRouterOptions<unknown>,
600
642
  routePath: path,
601
643
  });
602
644
  }
@@ -619,7 +661,7 @@ export function modelRouter<T>(
619
661
  return router;
620
662
  }
621
663
 
622
- function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
664
+ const _buildModelRouter = <T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router => {
623
665
  const router = express.Router();
624
666
 
625
667
  assertNoActionCollisions(model, options);
@@ -650,14 +692,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
650
692
  try {
651
693
  body = transform<T>(options, req.body, "create", req.user);
652
694
  } catch (error: unknown) {
653
- if (isAPIError(error)) {
654
- throw error;
655
- }
656
- throw new APIError({
657
- cause: error,
695
+ throw passthroughOrWrap(error, {
658
696
  code: "transform-error",
659
- detail: errorMessage(error),
660
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
661
697
  status: 400,
662
698
  title: "Transform error",
663
699
  });
@@ -666,37 +702,31 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
666
702
  try {
667
703
  body = await options.preCreate(body, req);
668
704
  } catch (error: unknown) {
669
- if (isAPIError(error)) {
670
- throw error;
671
- }
672
- throw new APIError({
673
- cause: error,
705
+ throw passthroughOrWrap(error, {
674
706
  code: "pre-create-hook-error",
675
- detail: errorMessage(error),
676
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
677
707
  status: 400,
678
708
  title: "preCreate hook error",
679
709
  });
680
710
  }
681
711
  if (body === undefined) {
682
- throw new APIError({
712
+ throw new ForbiddenError({
713
+ code: "create-not-allowed",
683
714
  detail: "A body must be returned from preCreate",
684
- status: 403,
685
715
  title: "Create not allowed",
686
716
  });
687
717
  }
688
718
  if (body === null) {
689
- throw new APIError({
719
+ throw new ForbiddenError({
720
+ code: "create-not-allowed",
690
721
  detail: "preCreate hook returned null",
691
- status: 403,
692
722
  title: "Create not allowed",
693
723
  });
694
724
  }
695
725
  }
696
726
  if (body === undefined) {
697
- throw new APIError({
727
+ throw new BadRequestError({
728
+ code: "invalid-request-body",
698
729
  detail: "Body is undefined",
699
- status: 400,
700
730
  title: "Invalid request body",
701
731
  });
702
732
  }
@@ -704,11 +734,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
704
734
  try {
705
735
  data = (await model.create(body as T)) as Document<unknown, unknown, unknown> & T;
706
736
  } catch (error: unknown) {
707
- throw new APIError({
708
- cause: error,
737
+ throw passthroughOrWrapWrite(error, {
709
738
  code: "create-error",
710
- detail: errorMessage(error),
711
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
712
739
  status: 400,
713
740
  title: "Create error",
714
741
  });
@@ -722,11 +749,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
722
749
  populateQuery = addPopulateToQuery(populateQuery, options.populatePaths);
723
750
  data = await populateQuery.exec();
724
751
  } catch (error: unknown) {
725
- throw new APIError({
726
- cause: error,
752
+ throw passthroughOrWrap(error, {
727
753
  code: "populate-error",
728
- detail: errorMessage(error),
729
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
730
754
  status: 400,
731
755
  title: "Populate error",
732
756
  });
@@ -737,11 +761,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
737
761
  try {
738
762
  await options.postCreate(data, req);
739
763
  } catch (error: unknown) {
740
- throw new APIError({
741
- cause: error,
764
+ throw passthroughOrWrap(error, {
742
765
  code: "post-create-hook-error",
743
- detail: errorMessage(error),
744
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
745
766
  status: 400,
746
767
  title: "postCreate hook error",
747
768
  });
@@ -751,11 +772,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
751
772
  const serialized = await responseHandler(data, "create", req, options);
752
773
  return res.status(201).json({data: serialized});
753
774
  } catch (error: unknown) {
754
- throw new APIError({
755
- cause: error,
775
+ throw passthroughOrWrap(error, {
756
776
  code: "response-handler-error",
757
- detail: errorMessage(error),
758
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
759
777
  title: "responseHandler error",
760
778
  });
761
779
  }
@@ -810,11 +828,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
810
828
  try {
811
829
  queryFilter = await options.queryFilter(req.user, query);
812
830
  } catch (error: unknown) {
813
- throw new APIError({
814
- cause: error,
831
+ throw passthroughOrWrap(error, {
815
832
  code: "query-filter-error",
816
- detail: String(error),
817
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
818
833
  status: 400,
819
834
  title: "Query filter error",
820
835
  });
@@ -843,9 +858,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
843
858
  const total = await model.countDocuments(query);
844
859
  if (req.query.page) {
845
860
  if (Number(req.query.page) === 0 || Number.isNaN(Number(req.query.page))) {
846
- throw new APIError({
847
- status: 400,
848
- title: `Invalid page: ${req.query.page}`,
861
+ throw new BadRequestError({
862
+ code: "invalid-page",
863
+ detail: `Invalid page: ${req.query.page}`,
864
+ source: {parameter: "page"},
865
+ title: "Invalid page",
849
866
  });
850
867
  }
851
868
  builtQuery = builtQuery.skip((Number(req.query.page) - 1) * limit);
@@ -864,11 +881,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
864
881
  try {
865
882
  data = (await populatedQuery.exec()) as (Document<unknown, unknown, unknown> & T)[];
866
883
  } catch (error: unknown) {
867
- throw new APIError({
868
- cause: error,
884
+ throw passthroughOrWrap(error, {
869
885
  code: "list-error",
870
- detail: errorMessage(error),
871
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
872
886
  title: "List error",
873
887
  });
874
888
  }
@@ -878,11 +892,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
878
892
  try {
879
893
  serialized = await responseHandler(data, "list", req, options);
880
894
  } catch (error: unknown) {
881
- throw new APIError({
882
- cause: error,
895
+ throw passthroughOrWrap(error, {
883
896
  code: "response-handler-error",
884
- detail: errorMessage(error),
885
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
886
897
  title: "responseHandler error",
887
898
  });
888
899
  }
@@ -915,11 +926,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
915
926
  }
916
927
  return res.json({data: serialized});
917
928
  } catch (error: unknown) {
918
- throw new APIError({
919
- cause: error,
929
+ throw passthroughOrWrap(error, {
920
930
  code: "serialization-error",
921
- detail: errorMessage(error),
922
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
923
931
  title: "Serialization error",
924
932
  });
925
933
  }
@@ -940,11 +948,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
940
948
  const serialized = await responseHandler(data, "read", req, options);
941
949
  return res.json({data: serialized});
942
950
  } catch (error: unknown) {
943
- throw new APIError({
944
- cause: error,
951
+ throw passthroughOrWrap(error, {
945
952
  code: "response-handler-error",
946
- detail: errorMessage(error),
947
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
948
953
  title: "responseHandler error",
949
954
  });
950
955
  }
@@ -957,6 +962,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
957
962
  asyncHandler(async (_req: Request, _res: Response) => {
958
963
  // Patch is what we want 90% of the time
959
964
  throw new APIError({
965
+ code: "put-not-supported",
966
+ detail: "Use PATCH to update a document.",
960
967
  title: "PUT is not supported.",
961
968
  });
962
969
  })
@@ -978,14 +985,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
978
985
  try {
979
986
  body = transform<T>(options, req.body, "update", req.user) as Partial<T>;
980
987
  } catch (error: unknown) {
981
- if (isAPIError(error)) {
982
- throw error;
983
- }
984
- throw new APIError({
985
- cause: error,
988
+ throw passthroughOrWrap(error, {
986
989
  code: "transform-error",
987
- detail: `PATCH failed on ${req.params.id} for user ${req.user?.id}: ${errorMessage(error)}`,
988
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
990
+ detail: `PATCH failed on ${req.params.id} for user ${req.user?.id}: ${errorDetail(error)}`,
989
991
  status: 403,
990
992
  title: "PATCH failed",
991
993
  });
@@ -1002,29 +1004,24 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1002
1004
  try {
1003
1005
  body = await options.preUpdate(body, req);
1004
1006
  } catch (error: unknown) {
1005
- if (isAPIError(error)) {
1006
- throw error;
1007
- }
1008
- throw new APIError({
1009
- cause: error,
1007
+ throw passthroughOrWrap(error, {
1010
1008
  code: "pre-update-hook-error",
1011
- detail: `preUpdate hook error on ${req.params.id}: ${errorMessage(error)}`,
1012
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1009
+ detail: `preUpdate hook error on ${req.params.id}: ${errorDetail(error)}`,
1013
1010
  status: 400,
1014
1011
  title: "preUpdate hook error",
1015
1012
  });
1016
1013
  }
1017
1014
  if (body === undefined) {
1018
- throw new APIError({
1015
+ throw new ForbiddenError({
1016
+ code: "update-not-allowed",
1019
1017
  detail: "A body must be returned from preUpdate",
1020
- status: 403,
1021
1018
  title: "Update not allowed",
1022
1019
  });
1023
1020
  }
1024
1021
  if (body === null) {
1025
- throw new APIError({
1022
+ throw new ForbiddenError({
1023
+ code: "update-not-allowed",
1026
1024
  detail: `preUpdate hook on ${req.params.id} returned null`,
1027
- status: 403,
1028
1025
  title: "Update not allowed",
1029
1026
  });
1030
1027
  }
@@ -1050,13 +1047,13 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1050
1047
  : DateTime.fromISO(bodyUpdatedAt);
1051
1048
 
1052
1049
  if (!clientTimestamp.isValid) {
1053
- throw new APIError({
1050
+ throw new BadRequestError({
1051
+ code: "invalid-conflict-detection-timestamp",
1054
1052
  detail: usingPreciseHeader
1055
1053
  ? "X-Unmodified-Since-ISO header could not be parsed as an ISO date"
1056
1054
  : usingHttpHeader
1057
1055
  ? "If-Unmodified-Since header could not be parsed as an HTTP date"
1058
1056
  : "_updatedAt body field could not be parsed as an ISO date",
1059
- status: 400,
1060
1057
  title: "Invalid conflict-detection timestamp",
1061
1058
  });
1062
1059
  }
@@ -1071,9 +1068,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1071
1068
  }
1072
1069
 
1073
1070
  if (serverTimestamp && !serverTimestamp.isValid) {
1074
- throw new APIError({
1071
+ throw new BadRequestError({
1072
+ code: "invalid-server-timestamp",
1075
1073
  detail: "Document timestamp could not be parsed as a date",
1076
- status: 400,
1077
1074
  title: "Invalid server timestamp",
1078
1075
  });
1079
1076
  }
@@ -1097,11 +1094,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1097
1094
  doc.set(body);
1098
1095
  await doc.save();
1099
1096
  } catch (error: unknown) {
1100
- throw new APIError({
1101
- cause: error,
1097
+ throw passthroughOrWrapWrite(error, {
1102
1098
  code: "update-save-error",
1103
- detail: `preUpdate hook save error on ${req.params.id}: ${errorMessage(error)}`,
1104
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1099
+ detail: `preUpdate hook save error on ${req.params.id}: ${errorDetail(error)}`,
1105
1100
  status: 400,
1106
1101
  title: "preUpdate hook save error",
1107
1102
  });
@@ -1119,11 +1114,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1119
1114
  try {
1120
1115
  await options.postUpdate(doc, body, req, prevDoc);
1121
1116
  } catch (error: unknown) {
1122
- throw new APIError({
1123
- cause: error,
1117
+ throw passthroughOrWrap(error, {
1124
1118
  code: "post-update-hook-error",
1125
- detail: `postUpdate hook error on ${req.params.id}: ${errorMessage(error)}`,
1126
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1119
+ detail: `postUpdate hook error on ${req.params.id}: ${errorDetail(error)}`,
1127
1120
  status: 400,
1128
1121
  title: "postUpdate hook error",
1129
1122
  });
@@ -1134,11 +1127,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1134
1127
  const serialized = await responseHandler(doc, "update", req, options);
1135
1128
  return res.json({data: serialized});
1136
1129
  } catch (error: unknown) {
1137
- throw new APIError({
1138
- cause: error,
1130
+ throw passthroughOrWrap(error, {
1139
1131
  code: "response-handler-error",
1140
- detail: errorMessage(error),
1141
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1142
1132
  title: "responseHandler error",
1143
1133
  });
1144
1134
  }
@@ -1162,29 +1152,24 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1162
1152
  try {
1163
1153
  body = await options.preDelete(doc, req);
1164
1154
  } catch (error: unknown) {
1165
- if (isAPIError(error)) {
1166
- throw error;
1167
- }
1168
- throw new APIError({
1169
- cause: error,
1155
+ throw passthroughOrWrap(error, {
1170
1156
  code: "pre-delete-hook-error",
1171
- detail: `preDelete hook error on ${req.params.id}: ${errorMessage(error)}`,
1172
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1157
+ detail: `preDelete hook error on ${req.params.id}: ${errorDetail(error)}`,
1173
1158
  status: 403,
1174
1159
  title: "preDelete hook error",
1175
1160
  });
1176
1161
  }
1177
1162
  if (body === undefined) {
1178
- throw new APIError({
1163
+ throw new ForbiddenError({
1164
+ code: "delete-not-allowed",
1179
1165
  detail: "A body must be returned from preDelete",
1180
- status: 403,
1181
1166
  title: "Delete not allowed",
1182
1167
  });
1183
1168
  }
1184
1169
  if (body === null) {
1185
- throw new APIError({
1170
+ throw new ForbiddenError({
1171
+ code: "delete-not-allowed",
1186
1172
  detail: `preDelete hook for ${req.params.id} returned null`,
1187
- status: 403,
1188
1173
  title: "Delete not allowed",
1189
1174
  });
1190
1175
  }
@@ -1202,11 +1187,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1202
1187
  try {
1203
1188
  await doc.deleteOne();
1204
1189
  } catch (error: unknown) {
1205
- throw new APIError({
1206
- cause: error,
1190
+ throw passthroughOrWrap(error, {
1207
1191
  code: "delete-error",
1208
- detail: errorMessage(error),
1209
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1210
1192
  status: 400,
1211
1193
  title: "Delete error",
1212
1194
  });
@@ -1217,11 +1199,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1217
1199
  try {
1218
1200
  await options.postDelete(req, doc);
1219
1201
  } catch (error: unknown) {
1220
- throw new APIError({
1221
- cause: error,
1202
+ throw passthroughOrWrap(error, {
1222
1203
  code: "post-delete-hook-error",
1223
- detail: errorMessage(error),
1224
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1225
1204
  status: 400,
1226
1205
  title: "postDelete hook error",
1227
1206
  });
@@ -1241,8 +1220,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1241
1220
 
1242
1221
  if (!(await checkPermissions("update", options.permissions.update, req.user))) {
1243
1222
  throw new APIError({
1223
+ code: "array-update-not-allowed",
1224
+ detail: `Access to PATCH on ${model.modelName} denied for ${req.user?.id}`,
1225
+ meta: {method: "PATCH", model: model.modelName},
1244
1226
  status: 405,
1245
- title: `Access to PATCH on ${model.modelName} denied for ${req.user?.id}`,
1227
+ title: "Access denied",
1246
1228
  });
1247
1229
  }
1248
1230
 
@@ -1250,16 +1232,20 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1250
1232
  // Make a copy for passing pre-saved values to hooks.
1251
1233
  const prevDoc = cloneDeep(doc);
1252
1234
  if (!doc) {
1253
- throw new APIError({
1254
- status: 404,
1255
- title: `Could not find document to PATCH: ${req.params.id}`,
1235
+ throw new NotFoundError({
1236
+ code: "document-not-found",
1237
+ detail: `Could not find document to PATCH: ${req.params.id}`,
1238
+ meta: {model: model.modelName},
1239
+ title: "Document not found",
1256
1240
  });
1257
1241
  }
1258
1242
 
1259
1243
  if (!(await checkPermissions("update", options.permissions.update, req.user, doc))) {
1260
- throw new APIError({
1261
- status: 403,
1262
- title: `Patch not allowed for user ${req.user?.id} on doc ${doc._id}`,
1244
+ throw new ForbiddenError({
1245
+ code: "update-not-allowed",
1246
+ detail: `Patch not allowed for user ${req.user?.id} on doc ${doc._id}`,
1247
+ meta: {model: model.modelName},
1248
+ title: "Update not allowed",
1263
1249
  });
1264
1250
  }
1265
1251
 
@@ -1269,11 +1255,13 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1269
1255
  // We apply the operation *before* the hooks. As far as the callers are concerned, this should
1270
1256
  // be like PATCHing the field and replacing the whole thing.
1271
1257
  if (operation !== "DELETE" && req.body[field] === undefined) {
1272
- throw new APIError({
1273
- status: 400,
1274
- title: `Malformed body, array operations should have a single, top level key, got: ${Object.keys(
1258
+ throw new BadRequestError({
1259
+ code: "malformed-array-operation-body",
1260
+ detail: `Malformed body, array operations should have a single, top level key, got: ${Object.keys(
1275
1261
  req.body
1276
1262
  ).join(",")}`,
1263
+ meta: {field},
1264
+ title: "Malformed array operation body",
1277
1265
  });
1278
1266
  }
1279
1267
 
@@ -1289,9 +1277,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1289
1277
  index = array.indexOf(itemId);
1290
1278
  }
1291
1279
  if (index === -1) {
1292
- throw new APIError({
1293
- status: 404,
1294
- title: `Could not find ${field}/${itemId}`,
1280
+ throw new NotFoundError({
1281
+ code: "array-item-not-found",
1282
+ detail: `Could not find ${field}/${itemId}`,
1283
+ meta: {field, itemId},
1284
+ title: "Array item not found",
1295
1285
  });
1296
1286
  }
1297
1287
  // For PATCHing an item by ID, we need to merge the objects so we don't override the _id or
@@ -1305,9 +1295,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1305
1295
  array.splice(index, 1);
1306
1296
  }
1307
1297
  } else {
1308
- throw new APIError({
1309
- status: 400,
1310
- title: `Invalid array operation: ${operation}`,
1298
+ throw new BadRequestError({
1299
+ code: "invalid-array-operation",
1300
+ detail: `Invalid array operation: ${operation}`,
1301
+ meta: {operation},
1302
+ title: "Invalid array operation",
1311
1303
  });
1312
1304
  }
1313
1305
  let body: Partial<T> | null = {[field]: array} as unknown as Partial<T>;
@@ -1315,14 +1307,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1315
1307
  try {
1316
1308
  body = transform<T>(options, body, "update", req.user) as Partial<T>;
1317
1309
  } catch (error: unknown) {
1318
- if (isAPIError(error)) {
1319
- throw error;
1320
- }
1321
- throw new APIError({
1322
- cause: error,
1310
+ throw passthroughOrWrap(error, {
1323
1311
  code: "transform-error",
1324
- detail: errorMessage(error),
1325
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1326
1312
  status: 403,
1327
1313
  title: "Transform error",
1328
1314
  });
@@ -1332,26 +1318,24 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1332
1318
  try {
1333
1319
  body = await options.preUpdate(body, req);
1334
1320
  } catch (error: unknown) {
1335
- throw new APIError({
1336
- cause: error,
1321
+ throw passthroughOrWrap(error, {
1337
1322
  code: "pre-update-hook-error",
1338
- detail: `preUpdate hook error on ${req.params.id}: ${errorMessage(error)}`,
1339
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1323
+ detail: `preUpdate hook error on ${req.params.id}: ${errorDetail(error)}`,
1340
1324
  status: 400,
1341
1325
  title: "preUpdate hook error",
1342
1326
  });
1343
1327
  }
1344
1328
  if (body === undefined) {
1345
- throw new APIError({
1329
+ throw new ForbiddenError({
1330
+ code: "update-not-allowed",
1346
1331
  detail: "A body must be returned from preUpdate",
1347
- status: 403,
1348
1332
  title: "Update not allowed",
1349
1333
  });
1350
1334
  }
1351
1335
  if (body === null) {
1352
- throw new APIError({
1336
+ throw new ForbiddenError({
1337
+ code: "update-not-allowed",
1353
1338
  detail: `preUpdate hook on ${req.params.id} returned null`,
1354
- status: 403,
1355
1339
  title: "Update not allowed",
1356
1340
  });
1357
1341
  }
@@ -1363,11 +1347,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1363
1347
  Object.assign(doc, body);
1364
1348
  await doc.save();
1365
1349
  } catch (error: unknown) {
1366
- throw new APIError({
1367
- cause: error,
1350
+ throw passthroughOrWrapWrite(error, {
1368
1351
  code: "update-save-error",
1369
- detail: `PATCH Pre Update error on ${req.params.id}: ${errorMessage(error)}`,
1370
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1352
+ detail: `PATCH Pre Update error on ${req.params.id}: ${errorDetail(error)}`,
1371
1353
  status: 400,
1372
1354
  title: "PATCH Pre Update error",
1373
1355
  });
@@ -1382,11 +1364,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1382
1364
  prevDoc as unknown as T
1383
1365
  );
1384
1366
  } catch (error: unknown) {
1385
- throw new APIError({
1386
- cause: error,
1367
+ throw passthroughOrWrap(error, {
1387
1368
  code: "post-update-hook-error",
1388
- detail: `PATCH Post Update error on ${req.params.id}: ${errorMessage(error)}`,
1389
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1369
+ detail: `PATCH Post Update error on ${req.params.id}: ${errorDetail(error)}`,
1390
1370
  status: 400,
1391
1371
  title: "PATCH Post Update error",
1392
1372
  });
@@ -1429,7 +1409,7 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1429
1409
  router.use(apiErrorMiddleware);
1430
1410
 
1431
1411
  return router;
1432
- }
1412
+ };
1433
1413
 
1434
1414
  /**
1435
1415
  * Options for the asyncHandler function.