@ontrails/store 1.0.0-beta.14 → 1.0.0-beta.15

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 (92) hide show
  1. package/.turbo/turbo-lint.log +1 -1
  2. package/CHANGELOG.md +7 -0
  3. package/README.md +126 -61
  4. package/dist/index.d.ts +2 -2
  5. package/dist/index.d.ts.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/index.js.map +1 -1
  8. package/dist/internal/signal-identity.d.ts +17 -0
  9. package/dist/internal/signal-identity.d.ts.map +1 -0
  10. package/dist/internal/signal-identity.js +81 -0
  11. package/dist/internal/signal-identity.js.map +1 -0
  12. package/dist/jsonfile/index.d.ts +3 -0
  13. package/dist/jsonfile/index.d.ts.map +1 -0
  14. package/dist/jsonfile/index.js +2 -0
  15. package/dist/jsonfile/index.js.map +1 -0
  16. package/dist/jsonfile/runtime.d.ts +19 -0
  17. package/dist/jsonfile/runtime.d.ts.map +1 -0
  18. package/dist/jsonfile/runtime.js +403 -0
  19. package/dist/jsonfile/runtime.js.map +1 -0
  20. package/dist/jsonfile/types.d.ts +40 -0
  21. package/dist/jsonfile/types.d.ts.map +1 -0
  22. package/dist/{drizzle → jsonfile}/types.js.map +1 -1
  23. package/dist/store.d.ts +8 -18
  24. package/dist/store.d.ts.map +1 -1
  25. package/dist/store.js +152 -94
  26. package/dist/store.js.map +1 -1
  27. package/dist/testing.d.ts +28 -0
  28. package/dist/testing.d.ts.map +1 -0
  29. package/dist/testing.js +90 -0
  30. package/dist/testing.js.map +1 -0
  31. package/dist/trails/crud.d.ts +38 -0
  32. package/dist/trails/crud.d.ts.map +1 -0
  33. package/dist/trails/crud.js +112 -0
  34. package/dist/trails/crud.js.map +1 -0
  35. package/dist/trails/index.d.ts +7 -0
  36. package/dist/trails/index.d.ts.map +1 -0
  37. package/dist/trails/index.js +4 -0
  38. package/dist/trails/index.js.map +1 -0
  39. package/dist/trails/reconcile.d.ts +36 -0
  40. package/dist/trails/reconcile.d.ts.map +1 -0
  41. package/dist/trails/reconcile.js +142 -0
  42. package/dist/trails/reconcile.js.map +1 -0
  43. package/dist/trails/sync.d.ts +25 -0
  44. package/dist/trails/sync.d.ts.map +1 -0
  45. package/dist/trails/sync.js +96 -0
  46. package/dist/trails/sync.js.map +1 -0
  47. package/dist/trails/utils.d.ts +51 -0
  48. package/dist/trails/utils.d.ts.map +1 -0
  49. package/dist/trails/utils.js +65 -0
  50. package/dist/trails/utils.js.map +1 -0
  51. package/dist/types.d.ts +205 -35
  52. package/dist/types.d.ts.map +1 -1
  53. package/package.json +6 -9
  54. package/src/__tests__/crud.test.ts +346 -0
  55. package/src/__tests__/jsonfile.test.ts +502 -0
  56. package/src/__tests__/store.test.ts +239 -33
  57. package/src/__tests__/sync-reconcile.test.ts +646 -0
  58. package/src/index.ts +12 -8
  59. package/src/internal/signal-identity.ts +162 -0
  60. package/src/jsonfile/index.ts +6 -0
  61. package/src/jsonfile/runtime.ts +702 -0
  62. package/src/jsonfile/types.ts +50 -0
  63. package/src/store.ts +296 -134
  64. package/src/testing.ts +175 -0
  65. package/src/trails/crud.ts +355 -0
  66. package/src/trails/index.ts +10 -0
  67. package/src/trails/reconcile.ts +281 -0
  68. package/src/trails/sync.ts +251 -0
  69. package/src/trails/utils.ts +96 -0
  70. package/src/types.ts +355 -63
  71. package/tsconfig.tests.json +10 -0
  72. package/tsconfig.tsbuildinfo +1 -1
  73. package/dist/drizzle/index.d.ts +0 -3
  74. package/dist/drizzle/index.d.ts.map +0 -1
  75. package/dist/drizzle/index.js +0 -2
  76. package/dist/drizzle/index.js.map +0 -1
  77. package/dist/drizzle/runtime.d.ts +0 -21
  78. package/dist/drizzle/runtime.d.ts.map +0 -1
  79. package/dist/drizzle/runtime.js +0 -458
  80. package/dist/drizzle/runtime.js.map +0 -1
  81. package/dist/drizzle/schema.d.ts +0 -15
  82. package/dist/drizzle/schema.d.ts.map +0 -1
  83. package/dist/drizzle/schema.js +0 -322
  84. package/dist/drizzle/schema.js.map +0 -1
  85. package/dist/drizzle/types.d.ts +0 -40
  86. package/dist/drizzle/types.d.ts.map +0 -1
  87. package/src/drizzle/__tests__/drizzle.test.ts +0 -469
  88. package/src/drizzle/index.ts +0 -17
  89. package/src/drizzle/runtime.ts +0 -853
  90. package/src/drizzle/schema.ts +0 -577
  91. package/src/drizzle/types.ts +0 -70
  92. /package/dist/{drizzle → jsonfile}/types.js +0 -0
package/src/types.ts CHANGED
@@ -1,5 +1,19 @@
1
+ import type { Signal } from '@ontrails/core';
2
+ import type { StoreAccessorProtocol } from '@ontrails/core/store';
1
3
  import type { z } from 'zod';
2
4
 
5
+ /**
6
+ * Backend-agnostic persistence shapes that a connector can interpret.
7
+ */
8
+ export type StoreKind = 'tabular' | 'document' | 'file' | 'kv' | 'cache';
9
+
10
+ /**
11
+ * Store-level options applied to the authored definition.
12
+ */
13
+ export interface StoreOptions {
14
+ readonly kind?: StoreKind;
15
+ }
16
+
3
17
  /**
4
18
  * Object schema accepted by the store definition layer.
5
19
  */
@@ -13,54 +27,110 @@ export type StoreFieldKey<TSchema extends StoreObjectSchema> = Extract<
13
27
  string
14
28
  >;
15
29
 
30
+ type VersionedSchema<
31
+ TSchema extends StoreObjectSchema,
32
+ TVersioned extends boolean | undefined,
33
+ > = TVersioned extends true
34
+ ? TSchema extends z.ZodObject<infer TShape>
35
+ ? z.ZodObject<TShape & { version: z.ZodNumber }>
36
+ : never
37
+ : TSchema;
38
+
16
39
  type GeneratedFieldNames<
17
40
  TSchema extends StoreObjectSchema,
18
- TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined,
41
+ TGenerated extends readonly string[] | undefined,
19
42
  > = TGenerated extends readonly StoreFieldKey<TSchema>[]
20
43
  ? TGenerated[number]
21
44
  : never;
22
45
 
46
+ // We intentionally use Zod v4's shape-routed object infer helpers here because
47
+ // the public z.input/z.output path widens away the generic equality we need at
48
+ // store/core trail boundaries. These $-prefixed helpers are semi-internal Zod
49
+ // v4 API; that maintenance tradeoff is acceptable here because the public path
50
+ // does not preserve the boundary-proof shape we need.
51
+ type ObjectInputOf<TShape extends z.ZodRawShape> = z.core.$InferObjectInput<
52
+ TShape,
53
+ Record<never, never>
54
+ >;
55
+
56
+ type ObjectOutputOf<TShape extends z.ZodRawShape> = z.core.$InferObjectOutput<
57
+ TShape,
58
+ Record<never, never>
59
+ >;
60
+
23
61
  /**
24
62
  * Seed row accepted for one table fixture.
25
63
  *
26
64
  * Generated fields may be supplied explicitly, but they are optional so test
27
65
  * fixtures can omit timestamps and similar server-managed values when the mock
28
66
  * store can synthesize them.
67
+ *
68
+ * Routes input inference through the object's `shape` via a conditional
69
+ * `infer` so fixture inputs stay structurally aligned with the derived
70
+ * create/upsert inputs they meet at store/core trail boundaries.
71
+ *
72
+ * This is not the same type-level path core's `deriveTrail()` uses — core
73
+ * still goes through `z.input<TContour>` / `z.output<TContour>` — but at
74
+ * concrete instantiations it collapses to the same structural fixture shape
75
+ * while preserving generic equality across the store/core seam.
29
76
  */
30
77
  export type StoreFixtureInput<
31
78
  TSchema extends StoreObjectSchema,
32
- TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
33
- | readonly StoreFieldKey<TSchema>[]
79
+ TGenerated extends readonly string[] | undefined =
80
+ | readonly string[]
34
81
  | undefined,
35
- > = Omit<
36
- z.input<TSchema>,
37
- Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.input<TSchema>>
38
- > &
39
- Partial<
40
- Pick<
41
- z.input<TSchema>,
42
- Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.input<TSchema>>
43
- >
44
- >;
82
+ > = [TSchema] extends [z.ZodObject<infer TShape>]
83
+ ? Omit<
84
+ ObjectInputOf<TShape>,
85
+ Extract<
86
+ GeneratedFieldNames<TSchema, TGenerated>,
87
+ keyof ObjectInputOf<TShape>
88
+ >
89
+ > &
90
+ Partial<
91
+ Pick<
92
+ ObjectInputOf<TShape>,
93
+ Extract<
94
+ GeneratedFieldNames<TSchema, TGenerated>,
95
+ keyof ObjectInputOf<TShape>
96
+ >
97
+ >
98
+ >
99
+ : never;
45
100
 
46
101
  /**
47
102
  * Normalized fixture row after schema validation and default application.
103
+ *
104
+ * Mirror of {@link StoreFixtureInput} on the output side — routed through
105
+ * `$InferObjectOutput<TShape, Record<never, never>>` so row types stay
106
+ * structurally aligned with the contour output shapes they compose against.
107
+ *
108
+ * As with {@link StoreFixtureInput}, this is a shape-routed equivalent rather
109
+ * than the identical `z.output<TSchema>` inference path core uses directly.
48
110
  */
49
111
  export type StoreFixtureRow<
50
112
  TSchema extends StoreObjectSchema,
51
- TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
52
- | readonly StoreFieldKey<TSchema>[]
113
+ TGenerated extends readonly string[] | undefined =
114
+ | readonly string[]
53
115
  | undefined,
54
- > = Omit<
55
- z.output<TSchema>,
56
- Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.output<TSchema>>
57
- > &
58
- Partial<
59
- Pick<
60
- z.output<TSchema>,
61
- Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.output<TSchema>>
62
- >
63
- >;
116
+ > = [TSchema] extends [z.ZodObject<infer TShape>]
117
+ ? Omit<
118
+ ObjectOutputOf<TShape>,
119
+ Extract<
120
+ GeneratedFieldNames<TSchema, TGenerated>,
121
+ keyof ObjectOutputOf<TShape>
122
+ >
123
+ > &
124
+ Partial<
125
+ Pick<
126
+ ObjectOutputOf<TShape>,
127
+ Extract<
128
+ GeneratedFieldNames<TSchema, TGenerated>,
129
+ keyof ObjectOutputOf<TShape>
130
+ >
131
+ >
132
+ >
133
+ : never;
64
134
 
65
135
  /**
66
136
  * Connector-owned search metadata.
@@ -71,25 +141,62 @@ export type StoreFixtureRow<
71
141
  export type StoreSearchDefinition = Readonly<Record<string, unknown>>;
72
142
 
73
143
  /**
74
- * Authored metadata for one store table.
144
+ * Change signals projected from one store entity definition.
75
145
  */
76
- export interface StoreTableInput<
146
+ export interface StoreTableSignals<TPayload> {
147
+ readonly created: Signal<TPayload>;
148
+ readonly updated: Signal<TPayload>;
149
+ readonly removed: Signal<TPayload>;
150
+ }
151
+
152
+ /**
153
+ * Shared fields for all store table input variants.
154
+ */
155
+ interface StoreTableInputBase<
77
156
  TSchema extends StoreObjectSchema = StoreObjectSchema,
78
157
  TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
79
158
  | readonly StoreFieldKey<TSchema>[]
80
159
  | undefined,
160
+ TVersioned extends boolean | undefined = boolean | undefined,
81
161
  > {
82
- readonly fixtures?: readonly StoreFixtureInput<TSchema, TGenerated>[];
162
+ readonly fixtures?: readonly StoreFixtureInput<
163
+ VersionedSchema<TSchema, TVersioned>,
164
+ GeneratedFieldsOfShape<TSchema, TGenerated, TVersioned>
165
+ >[];
83
166
  readonly generated?: TGenerated;
167
+ readonly indexed?: readonly StoreFieldKey<TSchema>[];
84
168
  readonly indexes?: readonly StoreFieldKey<TSchema>[];
85
- readonly primaryKey: StoreFieldKey<TSchema>;
86
169
  readonly references?: Readonly<
87
170
  Partial<Record<StoreFieldKey<TSchema>, string>>
88
171
  >;
89
172
  readonly schema: TSchema;
90
173
  readonly search?: StoreSearchDefinition;
174
+ readonly versioned?: TVersioned;
91
175
  }
92
176
 
177
+ /**
178
+ * Authored metadata for one store entity.
179
+ *
180
+ * At least one of `identity` or `primaryKey` must be provided. Omitting both
181
+ * is a compile-time error — `resolveIdentity` would throw at runtime without
182
+ * this guard.
183
+ */
184
+ export type StoreTableInput<
185
+ TSchema extends StoreObjectSchema = StoreObjectSchema,
186
+ TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
187
+ | readonly StoreFieldKey<TSchema>[]
188
+ | undefined,
189
+ TVersioned extends boolean | undefined = boolean | undefined,
190
+ > =
191
+ | (StoreTableInputBase<TSchema, TGenerated, TVersioned> & {
192
+ readonly identity: StoreFieldKey<TSchema>;
193
+ readonly primaryKey?: StoreFieldKey<TSchema>;
194
+ })
195
+ | (StoreTableInputBase<TSchema, TGenerated, TVersioned> & {
196
+ readonly identity?: StoreFieldKey<TSchema>;
197
+ readonly primaryKey: StoreFieldKey<TSchema>;
198
+ });
199
+
93
200
  /**
94
201
  * Record of authored tables passed to `store(...)`.
95
202
  */
@@ -97,25 +204,82 @@ export type StoreTablesInput = Record<
97
204
  string,
98
205
  StoreTableInput<
99
206
  StoreObjectSchema,
100
- readonly StoreFieldKey<StoreObjectSchema>[] | undefined
207
+ readonly StoreFieldKey<StoreObjectSchema>[] | undefined,
208
+ boolean | undefined
101
209
  >
102
210
  >;
103
211
 
212
+ type DeclaredGeneratedFieldsOfInput<TInput extends StoreTableInput> =
213
+ TInput['generated'] extends readonly StoreFieldKey<TInput['schema']>[]
214
+ ? TInput['generated']
215
+ : readonly [];
216
+
217
+ type GeneratedFieldsOfShape<
218
+ TSchema extends StoreObjectSchema,
219
+ TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined,
220
+ TVersioned extends boolean | undefined,
221
+ > = TVersioned extends true
222
+ ? readonly [
223
+ ...(TGenerated extends readonly StoreFieldKey<TSchema>[]
224
+ ? TGenerated
225
+ : readonly []),
226
+ 'version',
227
+ ]
228
+ : TGenerated extends readonly StoreFieldKey<TSchema>[]
229
+ ? TGenerated
230
+ : readonly [];
231
+
232
+ type VersionedFieldsOfInput<TInput extends StoreTableInput> =
233
+ TInput['versioned'] extends true ? true : false;
234
+
235
+ type SchemaOfInput<TInput extends StoreTableInput> = VersionedSchema<
236
+ TInput['schema'],
237
+ VersionedFieldsOfInput<TInput>
238
+ >;
239
+
104
240
  /**
105
241
  * Preserve generated fields when present, otherwise normalize to an empty tuple.
106
242
  */
107
243
  export type GeneratedFieldsOfInput<TInput extends StoreTableInput> =
108
- TInput['generated'] extends readonly StoreFieldKey<TInput['schema']>[]
109
- ? TInput['generated']
110
- : readonly [];
244
+ GeneratedFieldsOfShape<
245
+ TInput['schema'],
246
+ DeclaredGeneratedFieldsOfInput<TInput>,
247
+ VersionedFieldsOfInput<TInput>
248
+ >;
249
+
250
+ /**
251
+ * Preserve the authored identity field.
252
+ */
253
+ export type IdentityFieldOfInput<TInput extends StoreTableInput> =
254
+ TInput['identity'] extends StoreFieldKey<TInput['schema']>
255
+ ? TInput['identity']
256
+ : TInput['primaryKey'] extends StoreFieldKey<TInput['schema']>
257
+ ? TInput['primaryKey']
258
+ : never;
111
259
 
112
260
  /**
113
- * Preserve index fields when present, otherwise normalize to an empty tuple.
261
+ * Preserve indexed fields when present, otherwise normalize to an empty tuple.
262
+ *
263
+ * At runtime `resolveIndexed` merges both `indexed` and `indexes` arrays, so
264
+ * this type mirrors that behavior: when both are present, the result is the
265
+ * union of both tuples. When only one is provided, it is used directly.
266
+ */
267
+ export type IndexedFieldsOfInput<TInput extends StoreTableInput> =
268
+ TInput['indexed'] extends readonly StoreFieldKey<TInput['schema']>[]
269
+ ? TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[]
270
+ ? readonly [...TInput['indexed'], ...TInput['indexes']]
271
+ : TInput['indexed']
272
+ : TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[]
273
+ ? TInput['indexes']
274
+ : readonly [];
275
+
276
+ /**
277
+ * Backward-compatible alias for code that still uses the SQL-shaped name.
114
278
  */
115
279
  export type IndexFieldsOfInput<TInput extends StoreTableInput> =
116
280
  TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[]
117
281
  ? TInput['indexes']
118
- : readonly [];
282
+ : IndexedFieldsOfInput<TInput>;
119
283
 
120
284
  /**
121
285
  * Preserve references when present, otherwise normalize to an empty object.
@@ -132,11 +296,11 @@ export type ReferencesOfInput<TInput extends StoreTableInput> =
132
296
  */
133
297
  export type FixturesOfInput<TInput extends StoreTableInput> =
134
298
  TInput['fixtures'] extends readonly StoreFixtureInput<
135
- TInput['schema'],
299
+ SchemaOfInput<TInput>,
136
300
  GeneratedFieldsOfInput<TInput>
137
301
  >[]
138
302
  ? readonly StoreFixtureRow<
139
- TInput['schema'],
303
+ SchemaOfInput<TInput>,
140
304
  GeneratedFieldsOfInput<TInput>
141
305
  >[]
142
306
  : readonly [];
@@ -151,14 +315,18 @@ export interface StoreTable<
151
315
  readonly fixtureSchema: StoreObjectSchema;
152
316
  readonly fixtures: FixturesOfInput<TInput>;
153
317
  readonly generated: GeneratedFieldsOfInput<TInput>;
154
- readonly indexes: IndexFieldsOfInput<TInput>;
318
+ readonly identity: IdentityFieldOfInput<TInput>;
319
+ readonly indexed: IndexedFieldsOfInput<TInput>;
320
+ readonly indexes: IndexedFieldsOfInput<TInput>;
155
321
  readonly insertSchema: StoreObjectSchema;
156
322
  readonly name: TName;
157
- readonly primaryKey: TInput['primaryKey'];
323
+ readonly primaryKey: IdentityFieldOfInput<TInput>;
158
324
  readonly references: ReferencesOfInput<TInput>;
159
- readonly schema: TInput['schema'];
160
- readonly search?: TInput['search'];
325
+ readonly schema: SchemaOfInput<TInput>;
326
+ readonly search?: StoreSearchDefinition | undefined;
327
+ readonly signals: StoreTableSignals<z.output<SchemaOfInput<TInput>>>;
161
328
  readonly updateSchema: StoreObjectSchema;
329
+ readonly versioned: VersionedFieldsOfInput<TInput>;
162
330
  }
163
331
 
164
332
  /**
@@ -170,7 +338,8 @@ export interface StoreDefinition<
170
338
  readonly get: <TName extends Extract<keyof TTables, string>>(
171
339
  name: TName
172
340
  ) => StoreTable<TTables[TName], TName>;
173
- readonly kind: 'store';
341
+ readonly kind: StoreKind;
342
+ readonly signals: readonly Signal<unknown>[];
174
343
  readonly tableNames: readonly Extract<keyof TTables, string>[];
175
344
  readonly tables: {
176
345
  readonly [TName in keyof TTables]: StoreTable<
@@ -178,6 +347,7 @@ export interface StoreDefinition<
178
347
  Extract<TName, string>
179
348
  >;
180
349
  };
350
+ readonly type: 'store';
181
351
  }
182
352
 
183
353
  /**
@@ -191,6 +361,8 @@ export interface AnyStoreTable {
191
361
  readonly fixtureSchema: StoreObjectSchema;
192
362
  readonly fixtures: readonly Record<string, unknown>[];
193
363
  readonly generated: readonly string[];
364
+ readonly identity: string;
365
+ readonly indexed: readonly string[];
194
366
  readonly indexes: readonly string[];
195
367
  readonly insertSchema: StoreObjectSchema;
196
368
  readonly name: string;
@@ -198,16 +370,20 @@ export interface AnyStoreTable {
198
370
  readonly references: Readonly<Partial<Record<string, string>>>;
199
371
  readonly schema: StoreObjectSchema;
200
372
  readonly search?: StoreSearchDefinition | undefined;
373
+ readonly signals: StoreTableSignals<unknown>;
201
374
  readonly updateSchema: StoreObjectSchema;
375
+ readonly versioned: boolean;
202
376
  }
203
377
 
204
378
  /**
205
379
  * Structural view of any normalized store definition.
206
380
  */
207
381
  export interface AnyStoreDefinition {
208
- readonly kind: 'store';
382
+ readonly kind: StoreKind;
383
+ readonly signals: readonly Signal<unknown>[];
209
384
  readonly tableNames: readonly string[];
210
385
  readonly tables: Readonly<Record<string, AnyStoreTable>>;
386
+ readonly type: 'store';
211
387
  }
212
388
 
213
389
  type GeneratedFieldKeysOf<TTable extends AnyStoreTable> = readonly Extract<
@@ -237,9 +413,9 @@ export type FixtureOf<TTable extends AnyStoreTable> = StoreFixtureRow<
237
413
  >;
238
414
 
239
415
  /**
240
- * Primary-key field name for one store table.
416
+ * Identity field name for one store entity.
241
417
  */
242
- export type PrimaryKeyOf<TTable extends AnyStoreTable> = TTable['primaryKey'];
418
+ export type IdentityOf<TTable extends AnyStoreTable> = TTable['identity'];
243
419
 
244
420
  /**
245
421
  * Server-managed fields for one store table.
@@ -252,21 +428,39 @@ export type GeneratedKeysOf<TTable extends AnyStoreTable> = Extract<
252
428
  /**
253
429
  * Insert shape: entity minus generated fields, with defaulted fields optional.
254
430
  *
255
- * Uses `z.input` so that fields with `.default()` are correctly represented as
256
- * optional in the insert shape (matching the runtime insert schema behavior).
431
+ * Routes through `$InferObjectInput<TShape, Record<never, never>>` via a
432
+ * conditional `infer` on the object's `shape`. At concrete instantiations
433
+ * this collapses to the same structural shape as
434
+ * `Omit<z.input<TTable['schema']>, GeneratedKeysOf<TTable>>`, but the
435
+ * shape-routed form lets TypeScript prove structural equality with
436
+ * `CreateInputOf<Contour, ...>` at trail boundaries without widening
437
+ * generic call sites to `Record<string, unknown>`.
438
+ *
439
+ * Defaulted fields remain optional because `$InferObjectInput` honors
440
+ * `OptionalInSchema`, mirroring the runtime insert schema behavior.
257
441
  */
258
- export type InsertOf<TTable extends AnyStoreTable> = Omit<
259
- z.input<TTable['schema']>,
260
- GeneratedKeysOf<TTable>
261
- >;
442
+ export type InsertOf<TTable extends AnyStoreTable> = [
443
+ TTable['schema'],
444
+ ] extends [z.ZodObject<infer TShape>]
445
+ ? Omit<ObjectInputOf<TShape>, GeneratedKeysOf<TTable>>
446
+ : never;
262
447
 
263
448
  /**
264
449
  * Update shape: partial insert minus the primary key (immutable identifier).
265
450
  */
266
451
  export type UpdateOf<TTable extends AnyStoreTable> = Partial<
267
- Omit<InsertOf<TTable>, PrimaryKeyOf<TTable>>
452
+ Omit<InsertOf<TTable>, IdentityOf<TTable>>
268
453
  >;
269
454
 
455
+ /**
456
+ * Upsert shape: entity payload with generated fields remaining optional.
457
+ *
458
+ * This matches the connector-agnostic "create or replace" contract while
459
+ * still allowing connectors to synthesize generated values like IDs and
460
+ * timestamps when the caller omits them.
461
+ */
462
+ export type UpsertOf<TTable extends AnyStoreTable> = FixtureInputOf<TTable>;
463
+
270
464
  /**
271
465
  * Typed filter shape for list operations.
272
466
  */
@@ -284,10 +478,10 @@ export interface StoreListOptions {
284
478
  * Shared identifier type for read/write accessors.
285
479
  */
286
480
  export type StoreIdentifierOf<TTable extends AnyStoreTable> =
287
- EntityOf<TTable>[Extract<PrimaryKeyOf<TTable>, keyof EntityOf<TTable>>];
481
+ EntityOf<TTable>[Extract<IdentityOf<TTable>, keyof EntityOf<TTable>>];
288
482
 
289
483
  /**
290
- * Access mode for a bound store connection or provision.
484
+ * Access mode for a bound store connection or resource.
291
485
  */
292
486
  export type StoreAccessMode = 'readonly' | 'readwrite';
293
487
 
@@ -295,7 +489,7 @@ export type StoreAccessMode = 'readonly' | 'readwrite';
295
489
  * Read-only table operations that every bound store must expose.
296
490
  */
297
491
  export interface ReadOnlyStoreTableAccessor<TTable extends AnyStoreTable> {
298
- /** Retrieve a single entity by primary key. Returns `null` when not found. */
492
+ /** Retrieve a single entity by identity. Returns `null` when not found. */
299
493
  get(id: StoreIdentifierOf<TTable>): Promise<EntityOf<TTable> | null>;
300
494
  /**
301
495
  * List entities, optionally filtered. Returns all rows when no filters are
@@ -308,13 +502,13 @@ export interface ReadOnlyStoreTableAccessor<TTable extends AnyStoreTable> {
308
502
  }
309
503
 
310
504
  /**
311
- * Writable table operations layered on top of the read contract.
505
+ * Connector-agnostic writable operations layered on top of the read contract.
312
506
  */
313
- export interface StoreTableAccessor<
507
+ export interface StoreAccessor<
314
508
  TTable extends AnyStoreTable,
315
509
  > extends ReadOnlyStoreTableAccessor<TTable> {
316
510
  /**
317
- * Insert a new entity.
511
+ * Create or replace one entity using the store's identity field.
318
512
  *
319
513
  * @throws {AlreadyExistsError} On primary key or unique constraint violation.
320
514
  *
@@ -322,19 +516,76 @@ export interface StoreTableAccessor<
322
516
  * This is an intentional throw-based boundary: store connectors throw typed
323
517
  * errors (`AlreadyExistsError`) rather than returning `Result`. Trail
324
518
  * implementations that call store accessors should catch and convert to
325
- * `Result.err()` at their level. A future `safeInsert` returning `Result`
519
+ * `Result.err()` at their level. A future safe variant returning `Result`
326
520
  * is planned but deferred to avoid cascading changes across all connectors.
327
521
  */
328
- insert(input: InsertOf<TTable>): Promise<EntityOf<TTable>>;
522
+ upsert(input: UpsertOf<TTable>): Promise<EntityOf<TTable>>;
329
523
  /**
330
- * Remove an entity by primary key. Returns `{ deleted: true }` when the
524
+ * Remove an entity by identity. Returns `{ deleted: true }` when the
331
525
  * row was found and removed, `{ deleted: false }` when no matching row
332
526
  * existed (not an error).
333
527
  */
334
528
  remove(id: StoreIdentifierOf<TTable>): Promise<{ readonly deleted: boolean }>;
529
+ }
530
+
531
+ // ---------------------------------------------------------------------------
532
+ // Compile-time assertion: StoreAccessor satisfies the core accessor protocol.
533
+ //
534
+ // `@ontrails/core/store` declares a structural protocol that `deriveTrail()`
535
+ // uses to synthesize default blazes without importing `@ontrails/store`. We
536
+ // pin the relationship here rather than in core so that any drift between
537
+ // the two shapes fails the store build immediately. If this check fails, the
538
+ // protocol in core has diverged from the store accessor contract — fix the
539
+ // protocol shape, not this assertion.
540
+ // ---------------------------------------------------------------------------
541
+
542
+ type AssertExtends<TActual, TExpected> = TActual extends TExpected
543
+ ? true
544
+ : never;
545
+
546
+ /**
547
+ * Pins the structural relationship between `StoreAccessor` and the core
548
+ * `StoreAccessorProtocol`. Exported so `noUnusedLocals` sees it as live; the
549
+ * type is purely a compile-time marker and contributes no runtime shape. If
550
+ * this type ever resolves to `never`, the protocol in core has drifted from
551
+ * the store accessor contract — fix the protocol shape, not this assertion.
552
+ */
553
+ export type AssertStoreAccessorSatisfiesProtocol = AssertExtends<
554
+ StoreAccessor<AnyStoreTable>,
555
+ StoreAccessorProtocol<
556
+ UpsertOf<AnyStoreTable>,
557
+ EntityOf<AnyStoreTable>,
558
+ StoreIdentifierOf<AnyStoreTable>,
559
+ FiltersOf<AnyStoreTable>
560
+ >
561
+ >;
562
+
563
+ /**
564
+ * Tabular writable operations layered on top of the connector-agnostic
565
+ * contract.
566
+ */
567
+ export interface StoreTableAccessor<
568
+ TTable extends AnyStoreTable,
569
+ > extends StoreAccessor<TTable> {
570
+ /**
571
+ * Insert a new entity.
572
+ *
573
+ * Tabular connectors can expose this convenience when the backend has a
574
+ * native distinction between create and update.
575
+ */
576
+ insert(input: InsertOf<TTable>): Promise<EntityOf<TTable>>;
335
577
  /**
336
- * Patch an entity by primary key with partial fields. Returns the updated
578
+ * Patch an entity by identity with partial fields. Returns the updated
337
579
  * entity, or `null` when no row with that ID exists.
580
+ *
581
+ * @remarks
582
+ * On versioned tables, `update` does **not** participate in optimistic
583
+ * concurrency control. The `UpdateOf<TTable>` shape is derived by omitting
584
+ * generated fields — including the framework-managed `version` column — so
585
+ * any `version` value is dropped before reaching the connector and the
586
+ * connector always auto-increments without comparing. Callers that need
587
+ * lost-update protection must use {@link StoreAccessor.upsert | `upsert`}
588
+ * instead and pass the expected `version` in the payload.
338
589
  */
339
590
  update(
340
591
  id: StoreIdentifierOf<TTable>,
@@ -352,10 +603,51 @@ export type ReadOnlyStoreConnection<TStore extends AnyStoreDefinition> = {
352
603
  };
353
604
 
354
605
  /**
355
- * Connection shape exposed by a writable bound store.
606
+ * Connector-agnostic connection shape exposed by a writable bound store.
356
607
  */
357
608
  export type StoreConnection<TStore extends AnyStoreDefinition> = {
609
+ readonly [TName in keyof TStore['tables']]: StoreAccessor<
610
+ TStore['tables'][TName]
611
+ >;
612
+ };
613
+
614
+ /**
615
+ * Tabular connection shape exposed by connectors that distinguish insert and
616
+ * patch operations from the generalized `upsert` contract.
617
+ */
618
+ export type StoreTableConnection<TStore extends AnyStoreDefinition> = {
358
619
  readonly [TName in keyof TStore['tables']]: StoreTableAccessor<
359
620
  TStore['tables'][TName]
360
621
  >;
361
622
  };
623
+
624
+ /**
625
+ * Optional fixture overrides used when building a mock store connection.
626
+ *
627
+ * The shape is a partial map keyed by table name; each entry is a list of
628
+ * fixture inputs validated against the table's fixture schema. Connectors
629
+ * share this type so every store backend seeds mocks the same way.
630
+ */
631
+ export type StoreMockSeed<TDef extends AnyStoreDefinition> = Partial<{
632
+ readonly [TName in keyof TDef['tables']]: readonly FixtureInputOf<
633
+ TDef['tables'][TName]
634
+ >[];
635
+ }>;
636
+
637
+ /**
638
+ * Shared connector options every store backend accepts.
639
+ *
640
+ * Concrete connectors extend this shape with their backend-specific fields
641
+ * (e.g. `url`, `dir`). Aligning the authored surface here lets the framework
642
+ * reason about connector options uniformly — one shape, many projections.
643
+ */
644
+ export interface StoreConnectorOptions<TDef extends AnyStoreDefinition> {
645
+ /** Optional resource id override. Defaults to `"store"`. */
646
+ readonly id?: string;
647
+ /** Human-readable description surfaced on the resource definition. */
648
+ readonly description?: string;
649
+ /** Free-form metadata for downstream tooling and governance. */
650
+ readonly meta?: Record<string, unknown>;
651
+ /** Optional per-table fixture overrides used by the mock resource factory. */
652
+ readonly mockSeed?: StoreMockSeed<TDef>;
653
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "compilerOptions": {
4
+ "noEmit": true,
5
+ "rootDir": "./src",
6
+ "types": ["bun"]
7
+ },
8
+ "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts"],
9
+ "exclude": []
10
+ }
@@ -1 +1 @@
1
- {"root":["./src/index.ts","./src/store.ts","./src/types.ts","./src/drizzle/index.ts","./src/drizzle/runtime.ts","./src/drizzle/schema.ts","./src/drizzle/types.ts"],"version":"5.9.3"}
1
+ {"root":["./src/index.ts","./src/store.ts","./src/testing.ts","./src/types.ts","./src/internal/signal-identity.ts","./src/jsonfile/index.ts","./src/jsonfile/runtime.ts","./src/jsonfile/types.ts","./src/trails/crud.ts","./src/trails/index.ts","./src/trails/reconcile.ts","./src/trails/sync.ts","./src/trails/utils.ts"],"version":"5.9.3"}
@@ -1,3 +0,0 @@
1
- export { connectDrizzle, connectReadOnlyDrizzle, getSchema, readonlyStore, store, } from './runtime.js';
2
- export type { ConnectDrizzleOptions, DrizzleMockSeed, DrizzleQueryContext, DrizzleStoreConnection, DrizzleStoreProvision, DrizzleStoreSchema, ReadOnlyDrizzleOptions, ReadOnlyDrizzleStoreConnection, } from './types.js';
3
- //# sourceMappingURL=index.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drizzle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,KAAK,GACN,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,YAAY,CAAC"}
@@ -1,2 +0,0 @@
1
- export { connectDrizzle, connectReadOnlyDrizzle, getSchema, readonlyStore, store, } from './runtime.js';
2
- //# sourceMappingURL=index.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/drizzle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,KAAK,GACN,MAAM,cAAc,CAAC"}