@terreno/api 57.1.0 → 57.3.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 (283) hide show
  1. package/README.md +17 -7
  2. package/dist/actions.js +19 -7
  3. package/dist/adminTypes.d.ts +26 -0
  4. package/dist/api.d.ts +4 -0
  5. package/dist/api.js +12 -24
  6. package/dist/auth.d.ts +23 -10
  7. package/dist/auth.js +97 -32
  8. package/dist/authRecovery.d.ts +5 -0
  9. package/dist/authRecovery.js +350 -0
  10. package/dist/authTokens.d.ts +8 -0
  11. package/dist/authTokens.js +162 -0
  12. package/dist/betterAuth.d.ts +33 -0
  13. package/dist/betterAuthApp.d.ts +4 -0
  14. package/dist/betterAuthApp.js +26 -8
  15. package/dist/betterAuthSetup.d.ts +44 -2
  16. package/dist/betterAuthSetup.js +288 -18
  17. package/dist/collectionRegistry.d.ts +38 -0
  18. package/dist/collectionRegistry.js +72 -0
  19. package/dist/configurationApp.d.ts +11 -2
  20. package/dist/configurationApp.js +2 -4
  21. package/dist/docLoader.js +35 -6
  22. package/dist/expressServer.d.ts +26 -3
  23. package/dist/expressServer.js +79 -11
  24. package/dist/index.d.ts +16 -0
  25. package/dist/index.js +38 -2
  26. package/dist/mcp/auth.d.ts +1 -0
  27. package/dist/mcp/auth.js +47 -25
  28. package/dist/mcp/handlers.d.ts +1 -1
  29. package/dist/mcp/handlers.js +67 -233
  30. package/dist/mcp/query.d.ts +2 -2
  31. package/dist/mcp/registry.d.ts +1 -5
  32. package/dist/mcp/registry.js +31 -20
  33. package/dist/mcp/schemaGenerator.d.ts +2 -7
  34. package/dist/mcp/schemaGenerator.js +41 -116
  35. package/dist/mcp/server.d.ts +1 -0
  36. package/dist/mcp/server.js +1 -0
  37. package/dist/mcp/serviceTokens.d.ts +16 -0
  38. package/dist/mcp/serviceTokens.js +345 -0
  39. package/dist/mcp/types.d.ts +2 -2
  40. package/dist/models/mcpServiceToken.d.ts +3 -0
  41. package/dist/models/mcpServiceToken.js +208 -0
  42. package/dist/openApiBuilder.d.ts +5 -4
  43. package/dist/openApiBuilder.js +61 -8
  44. package/dist/openApiCompat.js +1 -1
  45. package/dist/openApiValidator.js +0 -2
  46. package/dist/plugins.d.ts +14 -1
  47. package/dist/plugins.js +17 -6
  48. package/dist/populate.d.ts +2 -2
  49. package/dist/populate.js +47 -42
  50. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  51. package/dist/rateLimit/applyTrustProxy.js +17 -0
  52. package/dist/rateLimit/createStore.d.ts +2 -0
  53. package/dist/rateLimit/createStore.js +28 -0
  54. package/dist/rateLimit/memoryStore.d.ts +2 -0
  55. package/dist/rateLimit/memoryStore.js +108 -0
  56. package/dist/rateLimit/middleware.d.ts +11 -0
  57. package/dist/rateLimit/middleware.js +110 -0
  58. package/dist/rateLimit/mongoStore.d.ts +3 -0
  59. package/dist/rateLimit/mongoStore.js +122 -0
  60. package/dist/rateLimit/policies.d.ts +14 -0
  61. package/dist/rateLimit/policies.js +151 -0
  62. package/dist/rateLimit/redisStore.d.ts +3 -0
  63. package/dist/rateLimit/redisStore.js +155 -0
  64. package/dist/rateLimit/types.d.ts +54 -0
  65. package/dist/rateLimit/types.js +9 -0
  66. package/dist/rbac/access.js +5 -1
  67. package/dist/rbac/assertAllowed.d.ts +9 -0
  68. package/dist/rbac/assertAllowed.js +182 -0
  69. package/dist/rbac/modelRouterAccess.d.ts +1 -0
  70. package/dist/rbac/modelRouterAccess.js +8 -4
  71. package/dist/rbac/permissionUtils.js +3 -2
  72. package/dist/rbac/resolve.js +5 -4
  73. package/dist/rbac/routes.js +15 -6
  74. package/dist/rbac/statements.d.ts +10 -0
  75. package/dist/rbac/statements.js +13 -2
  76. package/dist/realtime/deprecation.d.ts +12 -0
  77. package/dist/realtime/deprecation.js +32 -0
  78. package/dist/realtime/realtimeApp.d.ts +1 -1
  79. package/dist/realtime/realtimeApp.js +10 -11
  80. package/dist/realtime/registry.d.ts +0 -31
  81. package/dist/realtime/registry.js +44 -31
  82. package/dist/realtime/socketAuth.d.ts +5 -5
  83. package/dist/realtime/socketAuth.js +11 -1
  84. package/dist/realtime/socketUser.d.ts +5 -1
  85. package/dist/realtime/types.d.ts +14 -4
  86. package/dist/schemaMetadata.d.ts +56 -0
  87. package/dist/schemaMetadata.js +513 -0
  88. package/dist/seedRunner.d.ts +88 -0
  89. package/dist/seedRunner.js +627 -0
  90. package/dist/sync/executors.d.ts +12 -2
  91. package/dist/sync/executors.js +8 -10
  92. package/dist/sync/loadHarness.js +28 -19
  93. package/dist/sync/models.js +26 -24
  94. package/dist/sync/mutationHandler.d.ts +9 -0
  95. package/dist/sync/mutationHandler.js +11 -6
  96. package/dist/sync/registrationSideEffects.d.ts +35 -0
  97. package/dist/sync/registrationSideEffects.js +151 -0
  98. package/dist/sync/registry.d.ts +2 -52
  99. package/dist/sync/registry.js +38 -187
  100. package/dist/sync/routes.js +3 -2
  101. package/dist/sync/scripts/compactTombstones.js +0 -2
  102. package/dist/sync/syncApp.d.ts +3 -3
  103. package/dist/sync/syncApp.js +4 -4
  104. package/dist/sync/syncBatch.js +3 -2
  105. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  106. package/dist/sync/syncSeqPlugin.js +20 -16
  107. package/dist/terrenoApp.d.ts +19 -5
  108. package/dist/terrenoApp.js +66 -18
  109. package/dist/tests/models.d.ts +2 -0
  110. package/dist/tests/models.js +6 -0
  111. package/dist/types/authToken.d.ts +33 -0
  112. package/dist/types/authToken.js +2 -0
  113. package/dist/types/mcpServiceToken.d.ts +41 -0
  114. package/dist/types/mcpServiceToken.js +2 -0
  115. package/dist/webhooks/headerValue.d.ts +2 -0
  116. package/dist/webhooks/headerValue.js +14 -0
  117. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  118. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  119. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  120. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  121. package/dist/webhooks/idempotency/webhookReceipt.d.ts +62 -0
  122. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  123. package/dist/webhooks/rawBody.d.ts +14 -0
  124. package/dist/webhooks/rawBody.js +22 -0
  125. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  126. package/dist/webhooks/timingSafeEqual.js +17 -0
  127. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  128. package/dist/webhooks/verifiers/hmac.js +49 -0
  129. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  130. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  131. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  132. package/dist/webhooks/verifiers/stripe.js +99 -0
  133. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  134. package/dist/webhooks/verifiers/twilio.js +112 -0
  135. package/dist/webhooks/webhooksApp.d.ts +33 -0
  136. package/dist/webhooks/webhooksApp.js +195 -0
  137. package/package.json +5 -6
  138. package/src/__snapshots__/openApi.test.ts.snap +270 -0
  139. package/src/__snapshots__/openApiBuilder.test.ts.snap +30 -12
  140. package/src/__snapshots__/schemaMetadata.test.ts.snap +197 -0
  141. package/src/actions.ts +20 -13
  142. package/src/adminModelRouter.test.ts +133 -0
  143. package/src/adminTypes.ts +23 -0
  144. package/src/api.arrayOperations.test.ts +43 -31
  145. package/src/api.hooks.test.ts +38 -29
  146. package/src/api.query.test.ts +31 -31
  147. package/src/api.test.ts +95 -96
  148. package/src/api.ts +16 -27
  149. package/src/auth.test.ts +107 -51
  150. package/src/auth.ts +98 -29
  151. package/src/authRecovery.test.ts +281 -0
  152. package/src/authRecovery.ts +279 -0
  153. package/src/authTokens.test.ts +94 -0
  154. package/src/authTokens.ts +118 -0
  155. package/src/authVerification.test.ts +293 -0
  156. package/src/betterAuth.ts +24 -0
  157. package/src/betterAuthApp.test.ts +1 -0
  158. package/src/betterAuthApp.ts +27 -9
  159. package/src/betterAuthSetup.test.ts +568 -38
  160. package/src/betterAuthSetup.ts +260 -5
  161. package/src/collectionRegistry.test.ts +165 -0
  162. package/src/collectionRegistry.ts +115 -0
  163. package/src/configurationApp.ts +13 -7
  164. package/src/docLoader.test.ts +45 -1
  165. package/src/docLoader.ts +37 -6
  166. package/src/express.d.ts +1 -0
  167. package/src/expressServer.test.ts +130 -66
  168. package/src/expressServer.ts +75 -19
  169. package/src/githubAuth.test.ts +60 -55
  170. package/src/index.ts +58 -0
  171. package/src/mcp/auth.test.ts +47 -0
  172. package/src/mcp/auth.ts +32 -11
  173. package/src/mcp/handlers.ts +45 -172
  174. package/src/mcp/integration.test.ts +59 -9
  175. package/src/mcp/query.ts +2 -4
  176. package/src/mcp/registry.ts +29 -20
  177. package/src/mcp/schemaGenerator.test.ts +8 -0
  178. package/src/mcp/schemaGenerator.ts +49 -131
  179. package/src/mcp/server.ts +2 -0
  180. package/src/mcp/serviceTokens.test.ts +330 -0
  181. package/src/mcp/serviceTokens.ts +307 -0
  182. package/src/mcp/toolGenerator.test.ts +1 -1
  183. package/src/mcp/types.ts +2 -6
  184. package/src/models/mcpServiceToken.test.ts +129 -0
  185. package/src/models/mcpServiceToken.ts +158 -0
  186. package/src/openApi.test.ts +80 -64
  187. package/src/openApiBuilder.test.ts +95 -7
  188. package/src/openApiBuilder.ts +46 -9
  189. package/src/openApiCompat.ts +1 -1
  190. package/src/openApiValidator.test.ts +49 -54
  191. package/src/openApiValidator.ts +1 -3
  192. package/src/plugins.test.ts +14 -0
  193. package/src/plugins.ts +34 -9
  194. package/src/populate.test.ts +34 -0
  195. package/src/populate.ts +40 -29
  196. package/src/rateLimit/applyTrustProxy.ts +17 -0
  197. package/src/rateLimit/createStore.ts +25 -0
  198. package/src/rateLimit/memoryStore.ts +40 -0
  199. package/src/rateLimit/middleware.ts +79 -0
  200. package/src/rateLimit/mongoStore.test.ts +80 -0
  201. package/src/rateLimit/mongoStore.ts +76 -0
  202. package/src/rateLimit/policies.ts +130 -0
  203. package/src/rateLimit/rateLimit.test.ts +328 -0
  204. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  205. package/src/rateLimit/redisStore.test.ts +114 -0
  206. package/src/rateLimit/redisStore.ts +85 -0
  207. package/src/rateLimit/types.ts +64 -0
  208. package/src/rbac/access.ts +5 -1
  209. package/src/rbac/assertAllowed.test.ts +325 -0
  210. package/src/rbac/assertAllowed.ts +157 -0
  211. package/src/rbac/backfillAdmins.test.ts +124 -0
  212. package/src/rbac/fieldViews.test.ts +89 -0
  213. package/src/rbac/modelRouterAccess.test.ts +126 -0
  214. package/src/rbac/modelRouterAccess.ts +5 -2
  215. package/src/rbac/permissionUtils.ts +3 -2
  216. package/src/rbac/realtimeAccess.test.ts +109 -1
  217. package/src/rbac/resolve.ts +5 -4
  218. package/src/rbac/roleManager.test.ts +169 -0
  219. package/src/rbac/routes.test.ts +233 -0
  220. package/src/rbac/routes.ts +16 -6
  221. package/src/rbac/statements.test.ts +2 -0
  222. package/src/rbac/statements.ts +12 -1
  223. package/src/realtime/deprecation.test.ts +60 -0
  224. package/src/realtime/deprecation.ts +32 -0
  225. package/src/realtime/realtime.test.ts +8 -4
  226. package/src/realtime/realtimeApp.ts +10 -11
  227. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  228. package/src/realtime/registry.ts +48 -42
  229. package/src/realtime/sessionRevalidation.test.ts +57 -44
  230. package/src/realtime/socketAuth.test.ts +75 -23
  231. package/src/realtime/socketAuth.ts +17 -6
  232. package/src/realtime/socketUser.ts +5 -3
  233. package/src/realtime/types.ts +14 -4
  234. package/src/schemaMetadata.test.ts +405 -0
  235. package/src/schemaMetadata.ts +593 -0
  236. package/src/scrubAdminFields.test.ts +105 -0
  237. package/src/seedRunner.test.ts +591 -0
  238. package/src/seedRunner.ts +464 -0
  239. package/src/sync/docMatchesMutationData.test.ts +16 -0
  240. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  241. package/src/sync/executors.test.ts +40 -0
  242. package/src/sync/executors.ts +24 -12
  243. package/src/sync/integration.test.ts +15 -7
  244. package/src/sync/loadHarness.ts +28 -19
  245. package/src/sync/models.ts +32 -18
  246. package/src/sync/mutationHandler.test.ts +16 -16
  247. package/src/sync/mutationHandler.ts +9 -7
  248. package/src/sync/registrationSideEffects.test.ts +126 -0
  249. package/src/sync/registrationSideEffects.ts +131 -0
  250. package/src/sync/registry.ts +45 -171
  251. package/src/sync/routes.ts +3 -2
  252. package/src/sync/scripts/compactTombstones.ts +0 -2
  253. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  254. package/src/sync/sync.test.ts +25 -23
  255. package/src/sync/syncApp.ts +4 -4
  256. package/src/sync/syncBatch.ts +3 -2
  257. package/src/sync/syncFrontier.test.ts +17 -15
  258. package/src/sync/syncPhaseC.test.ts +54 -43
  259. package/src/sync/syncRoutes.test.ts +51 -36
  260. package/src/sync/syncSeqPlugin.ts +66 -44
  261. package/src/sync/syncSocket.test.ts +112 -81
  262. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  263. package/src/terrenoApp.ts +87 -15
  264. package/src/tests/models.ts +14 -1
  265. package/src/types/authToken.ts +43 -0
  266. package/src/types/mcpServiceToken.ts +54 -0
  267. package/src/webhooks/headerValue.test.ts +22 -0
  268. package/src/webhooks/headerValue.ts +12 -0
  269. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  270. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  271. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  272. package/src/webhooks/idempotency/webhookReceipt.ts +70 -0
  273. package/src/webhooks/rawBody.test.ts +74 -0
  274. package/src/webhooks/rawBody.ts +23 -0
  275. package/src/webhooks/timingSafeEqual.ts +16 -0
  276. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  277. package/src/webhooks/verifiers/hmac.ts +54 -0
  278. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  279. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  280. package/src/webhooks/verifiers/stripe.ts +67 -0
  281. package/src/webhooks/verifiers/twilio.ts +69 -0
  282. package/src/webhooks/webhooksApp.test.ts +221 -0
  283. package/src/webhooks/webhooksApp.ts +144 -0
@@ -8,6 +8,9 @@ import type {BetterAuthSocketOptions} from "./socketAuth";
8
8
  /**
9
9
  * Configuration for real-time sync on a modelRouter.
10
10
  * Determines which CRUD methods emit WebSocket events and how they are routed.
11
+ *
12
+ * @deprecated Removed in Terreno 58. Use `sync` on modelRouter with `@terreno/syncdb`.
13
+ * `RealtimeApp` remains required for sync sockets.
11
14
  */
12
15
  export interface RealtimeConfig {
13
16
  /** Which CRUD methods should emit real-time sync events */
@@ -30,6 +33,9 @@ export interface RealtimeConfig {
30
33
 
31
34
  /**
32
35
  * A real-time sync event emitted to clients via WebSocket.
36
+ *
37
+ * @deprecated Removed in Terreno 58 with modelRouter `realtime` and the RTK
38
+ * cache-patching helpers. Syncdb uses `sync:delta` events instead.
33
39
  */
34
40
  export interface RealtimeEvent {
35
41
  /** Mongoose model name (e.g. "Todo") */
@@ -83,7 +89,10 @@ export interface RealtimeAppOptions {
83
89
  adapter?: "redis" | "none";
84
90
  /** Redis URL for the Redis adapter */
85
91
  redisUrl?: string;
86
- /** JWT secret for socket authentication (default: process.env.TOKEN_SECRET) */
92
+ /**
93
+ * JWT secret for socket authentication (default: process.env.TOKEN_SECRET).
94
+ * Optional when `betterAuth` is configured.
95
+ */
87
96
  tokenSecret?: string;
88
97
  /**
89
98
  * JWT issuer required for socket authentication (default: process.env.TOKEN_ISSUER),
@@ -92,9 +101,10 @@ export interface RealtimeAppOptions {
92
101
  */
93
102
  tokenIssuer?: string;
94
103
  /**
95
- * Enables the Better Auth session validator for socket authentication, tried after the
96
- * legacy JWT validator. Pass the instance returned by `createBetterAuth` (and optionally
97
- * the app user model so `decodedToken.id`/`admin` match the REST identity).
104
+ * Enables the Better Auth session validator for socket authentication. It is tried after
105
+ * the legacy JWT validator when a token secret exists, or used alone otherwise. Pass the
106
+ * instance returned by `createBetterAuth` (and optionally the app user model so
107
+ * `decodedToken.id`/`admin` match the REST identity).
98
108
  */
99
109
  betterAuth?: BetterAuthSocketOptions;
100
110
  /**
@@ -0,0 +1,405 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import mongoose, {Schema} from "mongoose";
3
+ import {z} from "zod";
4
+
5
+ import {
6
+ describeModel,
7
+ describeModelForRouter,
8
+ type FieldDescription,
9
+ fieldDescriptionToAdminMeta,
10
+ fieldDescriptionToOpenApiProperty,
11
+ fieldDescriptionToZodType,
12
+ modelDescriptionToAdminFields,
13
+ modelDescriptionToOpenApiSpec,
14
+ nestDottedFieldDescriptions,
15
+ } from "./schemaMetadata";
16
+
17
+ const fixtureSchema = new Schema({
18
+ completed: {default: false, description: "Whether the item is done", type: Boolean},
19
+ createdAt: {description: "When the record was created", type: Date},
20
+ label: {description: "Display label", required: true, type: String},
21
+ metadata: {description: "Arbitrary metadata", type: Schema.Types.Mixed},
22
+ ownerId: {description: "Owning user", ref: "User", required: true, type: Schema.Types.ObjectId},
23
+ status: {
24
+ description: "Workflow status",
25
+ enum: ["draft", "published"],
26
+ type: String,
27
+ },
28
+ tags: {description: "Search tags", type: [String]},
29
+ tasks: {
30
+ description: "Nested tasks",
31
+ type: [
32
+ new Schema({
33
+ done: {description: "Whether the task is done", type: Boolean},
34
+ title: {description: "Task title", required: true, type: String},
35
+ }),
36
+ ],
37
+ },
38
+ });
39
+
40
+ fixtureSchema.add({
41
+ created: {description: "Created timestamp", type: Date},
42
+ deleted: {default: false, description: "Soft delete flag", type: Boolean},
43
+ updated: {description: "Updated timestamp", type: Date},
44
+ });
45
+
46
+ const FixtureModel =
47
+ mongoose.models.SchemaMetadataFixture ?? mongoose.model("SchemaMetadataFixture", fixtureSchema);
48
+
49
+ const mapSchema = new Schema({
50
+ attributes: {description: "Untyped map values", type: Map},
51
+ checkboxValues: {description: "Boolean map", of: Boolean, type: Map},
52
+ lastEatenWith: {description: "Date map", of: Date, type: Map},
53
+ typedMap: {description: "String map", of: String, type: Map},
54
+ });
55
+
56
+ const MapModel =
57
+ mongoose.models.SchemaMetadataMap ?? mongoose.model("SchemaMetadataMap", mapSchema);
58
+
59
+ const embeddedSchema = new Schema({
60
+ profile: {
61
+ description: "Nested profile",
62
+ type: new Schema({
63
+ bio: {description: "Short bio", type: String},
64
+ }),
65
+ },
66
+ "settings.theme": {description: "Theme name", type: String},
67
+ });
68
+
69
+ const EmbeddedModel =
70
+ mongoose.models.SchemaMetadataEmbedded ??
71
+ mongoose.model("SchemaMetadataEmbedded", embeddedSchema);
72
+
73
+ describe("describeModel", () => {
74
+ it("returns a field graph snapshot for the fixture schema", () => {
75
+ const description = describeModel(FixtureModel);
76
+
77
+ expect(description.modelName).toBe("SchemaMetadataFixture");
78
+ expect(description.fields).toMatchSnapshot();
79
+ });
80
+
81
+ it("marks system fields", () => {
82
+ const description = describeModel(FixtureModel);
83
+
84
+ expect(description.fields._id?.system).toBe(true);
85
+ expect(description.fields.__v?.system).toBe(true);
86
+ expect(description.fields.created?.system).toBe(true);
87
+ expect(description.fields.updated?.system).toBe(true);
88
+ expect(description.fields.deleted?.system).toBe(true);
89
+ });
90
+
91
+ it("captures enum, ref, array, subdocument, and mixed fields", () => {
92
+ const description = describeModel(FixtureModel);
93
+
94
+ expect(description.fields.status).toEqual(
95
+ expect.objectContaining({
96
+ enum: ["draft", "published"],
97
+ kind: "string",
98
+ })
99
+ );
100
+ expect(description.fields.ownerId).toEqual(
101
+ expect.objectContaining({
102
+ kind: "objectId",
103
+ ref: "User",
104
+ required: true,
105
+ })
106
+ );
107
+ expect(description.fields.tags).toEqual(
108
+ expect.objectContaining({
109
+ isArray: true,
110
+ item: expect.objectContaining({kind: "string"}),
111
+ })
112
+ );
113
+ expect(description.fields.tasks).toEqual(
114
+ expect.objectContaining({
115
+ isArray: true,
116
+ item: expect.objectContaining({
117
+ fields: expect.objectContaining({
118
+ done: expect.objectContaining({kind: "boolean"}),
119
+ title: expect.objectContaining({kind: "string", required: true}),
120
+ }),
121
+ }),
122
+ })
123
+ );
124
+ expect(description.fields.metadata).toEqual(
125
+ expect.objectContaining({
126
+ kind: "mixed",
127
+ })
128
+ );
129
+ });
130
+
131
+ it("describes map fields from Map of/caster kinds, not a date fallback", () => {
132
+ const description = describeModel(MapModel);
133
+
134
+ expect(description.fields.attributes).toEqual(
135
+ expect.objectContaining({
136
+ item: expect.objectContaining({kind: "mixed"}),
137
+ kind: "map",
138
+ })
139
+ );
140
+ expect(description.fields.typedMap).toEqual(
141
+ expect.objectContaining({
142
+ item: expect.objectContaining({kind: "string"}),
143
+ kind: "map",
144
+ })
145
+ );
146
+ expect(description.fields.checkboxValues).toEqual(
147
+ expect.objectContaining({
148
+ item: expect.objectContaining({kind: "boolean"}),
149
+ kind: "map",
150
+ })
151
+ );
152
+ expect(description.fields.lastEatenWith).toEqual(
153
+ expect.objectContaining({
154
+ item: expect.objectContaining({kind: "date"}),
155
+ kind: "map",
156
+ })
157
+ );
158
+ expect(Object.keys(description.fields).some((path) => path.includes("$*"))).toBe(false);
159
+
160
+ expect(fieldDescriptionToOpenApiProperty(description.fields.lastEatenWith)).toEqual({
161
+ additionalProperties: {format: "date-time", type: "string"},
162
+ description: "Date map",
163
+ type: "object",
164
+ });
165
+ expect(fieldDescriptionToOpenApiProperty(description.fields.checkboxValues)).toEqual({
166
+ additionalProperties: {type: "boolean"},
167
+ description: "Boolean map",
168
+ type: "object",
169
+ });
170
+ expect(fieldDescriptionToOpenApiProperty(description.fields.typedMap)).toEqual({
171
+ additionalProperties: {type: "string"},
172
+ description: "String map",
173
+ type: "object",
174
+ });
175
+ });
176
+
177
+ it("merges extraProperties into the field graph", () => {
178
+ const extraField: FieldDescription = {
179
+ description: "Synthetic field",
180
+ kind: "string",
181
+ required: false,
182
+ };
183
+ const description = describeModel(FixtureModel, {
184
+ extraProperties: {synthetic: extraField},
185
+ });
186
+
187
+ expect(description.fields.synthetic).toEqual(extraField);
188
+ });
189
+ });
190
+
191
+ describe("describeModelForRouter", () => {
192
+ it("adds write masks from system fields and validation exclusions", () => {
193
+ const description = describeModelForRouter(FixtureModel, {
194
+ validation: {
195
+ excludeFromCreate: ["ownerId"],
196
+ excludeFromUpdate: ["status"],
197
+ },
198
+ });
199
+
200
+ expect(description.fields.created?.writableOnCreate).toBe(false);
201
+ expect(description.fields.ownerId?.writableOnCreate).toBe(false);
202
+ expect(description.fields.label?.writableOnCreate).toBe(true);
203
+ expect(description.fields.status?.writableOnUpdate).toBe(false);
204
+ expect(description.fields.label?.writableOnUpdate).toBe(true);
205
+ });
206
+
207
+ it("respects fieldView write masks for nested paths", () => {
208
+ const description = describeModelForRouter(EmbeddedModel, {
209
+ fieldView: {read: "*", write: ["profile"]},
210
+ });
211
+
212
+ expect(description.fields.profile?.writableOnCreate).toBe(true);
213
+ expect(description.fields["settings.theme"]?.writableOnCreate).toBe(false);
214
+ });
215
+ });
216
+
217
+ describe("nestDottedFieldDescriptions", () => {
218
+ it("nests dotted paths into embedded field graphs", () => {
219
+ const nested = nestDottedFieldDescriptions({
220
+ "settings.theme": {kind: "string", required: false},
221
+ title: {kind: "string", required: true},
222
+ });
223
+
224
+ expect(nested.settings).toEqual(
225
+ expect.objectContaining({
226
+ fields: {
227
+ theme: {kind: "string", required: false},
228
+ },
229
+ kind: "embedded",
230
+ })
231
+ );
232
+ expect(nested.title).toEqual({kind: "string", required: true});
233
+ });
234
+ });
235
+
236
+ describe("modelDescriptionToOpenApiSpec", () => {
237
+ it("converts the fixture description into OpenAPI properties", () => {
238
+ const description = describeModel(FixtureModel);
239
+ const spec = modelDescriptionToOpenApiSpec(description);
240
+
241
+ expect(spec.properties.ownerId).toEqual({
242
+ description: "Owning user",
243
+ format: "objectid",
244
+ type: "string",
245
+ });
246
+ expect(spec.properties.metadata).toEqual({
247
+ description: "Arbitrary metadata",
248
+ });
249
+ expect(spec.required).toContain("label");
250
+ expect(spec.required).toContain("ownerId");
251
+ expect(spec.properties.__v).toBeUndefined();
252
+ });
253
+ });
254
+
255
+ describe("fieldDescriptionToOpenApiProperty", () => {
256
+ it("maps arrays, embedded objects, maps, and date-only fields", () => {
257
+ const arrayField: FieldDescription = {
258
+ description: "Tags",
259
+ isArray: true,
260
+ item: {kind: "string", required: false},
261
+ kind: "string",
262
+ required: false,
263
+ };
264
+ const embeddedField: FieldDescription = {
265
+ description: "Profile",
266
+ fields: {
267
+ bio: {description: "Bio", kind: "string", required: false},
268
+ },
269
+ kind: "embedded",
270
+ required: false,
271
+ };
272
+ const mapField: FieldDescription = {
273
+ description: "Attributes",
274
+ item: {kind: "string", required: false},
275
+ kind: "map",
276
+ required: false,
277
+ };
278
+
279
+ expect(fieldDescriptionToOpenApiProperty(arrayField)).toEqual({
280
+ description: "Tags",
281
+ items: {type: "string"},
282
+ type: "array",
283
+ });
284
+ expect(fieldDescriptionToOpenApiProperty(embeddedField)).toEqual(
285
+ expect.objectContaining({
286
+ description: "Profile",
287
+ properties: {bio: {description: "Bio", type: "string"}},
288
+ type: "object",
289
+ })
290
+ );
291
+ expect(fieldDescriptionToOpenApiProperty(mapField)).toEqual({
292
+ additionalProperties: {type: "string"},
293
+ description: "Attributes",
294
+ type: "object",
295
+ });
296
+ expect(
297
+ fieldDescriptionToOpenApiProperty({
298
+ description: "Birthday",
299
+ kind: "dateOnly",
300
+ required: false,
301
+ })
302
+ ).toEqual({
303
+ description: "Birthday",
304
+ type: "dateonly",
305
+ });
306
+ });
307
+ });
308
+
309
+ describe("modelDescriptionToAdminFields", () => {
310
+ it("converts the fixture description into admin field metadata", () => {
311
+ const description = describeModel(FixtureModel);
312
+ const fields = modelDescriptionToAdminFields(description);
313
+
314
+ expect(fields.ownerId).toEqual(
315
+ expect.objectContaining({
316
+ ref: "User",
317
+ required: true,
318
+ searchable: false,
319
+ type: "objectid",
320
+ })
321
+ );
322
+ expect(fields.tags).toEqual(
323
+ expect.objectContaining({
324
+ itemType: "string",
325
+ type: "array",
326
+ })
327
+ );
328
+ expect(fields.tasks).toEqual(
329
+ expect.objectContaining({
330
+ items: expect.objectContaining({
331
+ title: expect.objectContaining({required: true, type: "string"}),
332
+ }),
333
+ type: "array",
334
+ })
335
+ );
336
+ });
337
+ });
338
+
339
+ describe("fieldDescriptionToAdminMeta", () => {
340
+ it("maps embedded object fields for admin forms", () => {
341
+ const meta = fieldDescriptionToAdminMeta({
342
+ description: "Profile",
343
+ fields: {
344
+ bio: {description: "Bio", kind: "string", required: false},
345
+ },
346
+ kind: "embedded",
347
+ required: false,
348
+ });
349
+
350
+ expect(meta).toEqual(
351
+ expect.objectContaining({
352
+ items: {
353
+ bio: expect.objectContaining({searchable: true, type: "string"}),
354
+ },
355
+ type: "object",
356
+ })
357
+ );
358
+ });
359
+ });
360
+
361
+ describe("fieldDescriptionToZodType", () => {
362
+ it("builds zod types for primitive, enum, array, and map fields", () => {
363
+ expect(fieldDescriptionToZodType({kind: "string", required: true}, z).parse("ok")).toBe("ok");
364
+ expect(
365
+ fieldDescriptionToZodType(
366
+ {enum: ["draft", "published"], kind: "string", required: true},
367
+ z
368
+ ).parse("draft")
369
+ ).toBe("draft");
370
+ expect(
371
+ fieldDescriptionToZodType(
372
+ {
373
+ description: "Tags",
374
+ isArray: true,
375
+ item: {kind: "string", required: false},
376
+ kind: "string",
377
+ required: false,
378
+ },
379
+ z
380
+ ).parse(["a"])
381
+ ).toEqual(["a"]);
382
+ expect(
383
+ fieldDescriptionToZodType(
384
+ {
385
+ description: "Attributes",
386
+ item: {kind: "string", required: false},
387
+ kind: "map",
388
+ required: false,
389
+ },
390
+ z
391
+ ).parse({key: "value"})
392
+ ).toEqual({key: "value"});
393
+ expect(
394
+ fieldDescriptionToZodType(
395
+ {
396
+ description: "Metadata",
397
+ fields: {note: {kind: "string", required: false}},
398
+ kind: "embedded",
399
+ required: false,
400
+ },
401
+ z
402
+ ).parse({note: "hello"})
403
+ ).toEqual({note: "hello"});
404
+ });
405
+ });