@baukit/data-contracts 0.7.2 → 0.7.3

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.
package/dist/erasure.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- /** Receipt returned after the server accepts or completes product-profile erasure. */
1
+ /** Server receipt or local fence confirmation. Rust wire receipts always have an operation ID. */
2
2
  export type ErasureReceipt = {
3
3
  readonly operationId: string | null;
4
4
  readonly status: 'completed';
@@ -1 +1 @@
1
- {"version":3,"file":"erasure.d.ts","sourceRoot":"","sources":["../src/erasure.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAExE,6DAA6D;AAC7D,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3F,gFAAgF;AAChF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,2BAA2B,GACnC;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,CAAC;AAEN,4EAA4E;AAC5E,qBAAa,mCAAoC,SAAQ,KAAK;IAC5D,SAAyB,IAAI,yCAAyC;IACtE,SAAgB,IAAI,EAAG,mCAAmC,CAAU;gBAEjD,KAAK,CAAC,EAAE,OAAO;CAGnC;AAuDD,qFAAqF;AACrF,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,iCAAiC,GAC9C,OAAO,CAAC,2BAA2B,CAAC,CAiDtC"}
1
+ {"version":3,"file":"erasure.d.ts","sourceRoot":"","sources":["../src/erasure.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAExE,6DAA6D;AAC7D,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3F,gFAAgF;AAChF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,2BAA2B,GACnC;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D,CAAC;AAEN,4EAA4E;AAC5E,qBAAa,mCAAoC,SAAQ,KAAK;IAC5D,SAAyB,IAAI,yCAAyC;IACtE,SAAgB,IAAI,EAAG,mCAAmC,CAAU;gBAEjD,KAAK,CAAC,EAAE,OAAO;CAGnC;AAuDD,qFAAqF;AACrF,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,iCAAiC,GAC9C,OAAO,CAAC,2BAA2B,CAAC,CAiDtC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@baukit/data-contracts",
3
- "version": "0.7.2",
3
+ "version": "0.7.3",
4
4
  "description": "Runtime-neutral data contracts, measurement helpers, and executable adapter conformance tests.",
5
5
  "license": "MIT",
6
6
  "author": "Patrick Koss",
@@ -59,6 +59,7 @@
59
59
  },
60
60
  "files": [
61
61
  "dist",
62
+ "src",
62
63
  "README.md",
63
64
  "LICENSE"
64
65
  ],
@@ -0,0 +1,160 @@
1
+ /** A value that can be represented without loss by JSON. */
2
+ export type JsonPrimitive = boolean | number | string | null;
3
+
4
+ /** A recursively JSON-serializable value. */
5
+ export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
6
+
7
+ /** A provider-neutral asynchronous string-keyed store. */
8
+ export interface KeyValueStore {
9
+ /** Returns `undefined` when the key does not exist. */
10
+ get(key: string): Promise<JsonValue | undefined>;
11
+ set(key: string, value: JsonValue): Promise<void>;
12
+ /** Deletes a key if present. Deleting a missing key is a no-op. */
13
+ delete(key: string): Promise<void>;
14
+ clear(): Promise<void>;
15
+ /**
16
+ * Deletes every key that starts with `prefix`, compared by UTF-16 code units and case-sensitively.
17
+ * No character in the prefix is a wildcard. An empty prefix clears the store.
18
+ */
19
+ clearPrefix(prefix: string): Promise<void>;
20
+ }
21
+
22
+ /** Records use an immutable string ID as their stable ordering and lookup key. */
23
+ export interface StoredRecord {
24
+ readonly id: string;
25
+ }
26
+
27
+ /** An opaque continuation token returned by a previous `list` call. */
28
+ export type Cursor = string;
29
+
30
+ export interface PageOptions {
31
+ /** Omit (or pass `null`) to begin at the first record. */
32
+ readonly cursor?: Cursor | null;
33
+ /** Must be an integer between 1 and `MAX_PAGE_SIZE`, inclusive. */
34
+ readonly limit?: number;
35
+ }
36
+
37
+ /** A cursor page. A null cursor means the page is terminal. */
38
+ export interface Page<T> {
39
+ readonly items: readonly T[];
40
+ readonly nextCursor: Cursor | null;
41
+ }
42
+
43
+ export const DEFAULT_PAGE_SIZE = 50;
44
+ export const MAX_PAGE_SIZE = 100;
45
+
46
+ /**
47
+ * A record store ordered by immutable `id`, ascending by JavaScript string
48
+ * comparison. Cursors are keyset positions: inserts before a returned cursor
49
+ * never shift or duplicate later pages.
50
+ */
51
+ export interface RecordStore<T extends StoredRecord> {
52
+ /** Inserts or replaces the record with the same ID. */
53
+ put(record: T): Promise<void>;
54
+ /** Returns `undefined` when the ID does not exist. */
55
+ get(id: string): Promise<T | undefined>;
56
+ /** Deletes a record if present. Deleting a missing ID is a no-op. */
57
+ delete(id: string): Promise<void>;
58
+ list(options?: PageOptions): Promise<Page<T>>;
59
+ }
60
+
61
+ /** Portable schema identity persisted alongside adapter data. */
62
+ export interface SchemaMeta {
63
+ readonly name: string;
64
+ /** A non-negative integer incremented for every schema change. */
65
+ readonly version: number;
66
+ }
67
+
68
+ export interface SchemaMetadataStore {
69
+ /** Returns `undefined` before metadata is initialized. */
70
+ getSchemaMeta(): Promise<SchemaMeta | undefined>;
71
+ setSchemaMeta(metadata: SchemaMeta): Promise<void>;
72
+ }
73
+
74
+ /** A product-provided hook used to move between two schema identities. */
75
+ export interface SchemaMigrationHook {
76
+ migrate(from: SchemaMeta, to: SchemaMeta): Promise<void>;
77
+ }
78
+
79
+ export type MaybePromise<T> = Promise<T> | T;
80
+
81
+ /** Stable machine-readable failures shared by storage adapters. */
82
+ export type StorageErrorCode = 'storage_closed' | 'storage_quota_exceeded';
83
+
84
+ /** A provider-neutral storage failure safe to branch on without parsing text. */
85
+ export class StorageError extends Error {
86
+ public override readonly name = 'StorageError';
87
+
88
+ public constructor(
89
+ public readonly code: StorageErrorCode,
90
+ message: string,
91
+ options?: ErrorOptions,
92
+ ) {
93
+ super(message, options);
94
+ }
95
+ }
96
+
97
+ /** Returns quota failures from nested adapter errors as one stable error. */
98
+ export function normalizeStorageError(cause: unknown): unknown {
99
+ if (cause instanceof StorageError) {
100
+ return cause;
101
+ }
102
+ let candidate: unknown = cause;
103
+ const visited = new Set<unknown>();
104
+ while (candidate !== null && candidate !== undefined && !visited.has(candidate)) {
105
+ visited.add(candidate);
106
+ if (errorField(candidate, 'name') === 'QuotaExceededError') {
107
+ return new StorageError(
108
+ 'storage_quota_exceeded',
109
+ 'Storage quota was exceeded; the write was not saved.',
110
+ { cause },
111
+ );
112
+ }
113
+ candidate = nestedError(candidate);
114
+ }
115
+ return cause;
116
+ }
117
+
118
+ function errorField(error: unknown, field: string): unknown {
119
+ return typeof error === 'object' && error !== null ? Reflect.get(error, field) : undefined;
120
+ }
121
+
122
+ function nestedError(error: unknown): unknown {
123
+ return errorField(error, 'cause') ?? errorField(error, 'inner');
124
+ }
125
+
126
+ /**
127
+ * Executes work against a transaction-scoped context. If the callback throws
128
+ * or rejects, none of its writes become visible. Its return value is preserved.
129
+ */
130
+ export interface Transaction<TContext> {
131
+ withTransaction<TResult>(
132
+ operation: (context: TContext) => MaybePromise<TResult>,
133
+ ): Promise<TResult>;
134
+ }
135
+
136
+ /** The standard transaction view used by composite storage adapters. */
137
+ export interface StorageTransaction<T extends StoredRecord> {
138
+ readonly keyValues: KeyValueStore;
139
+ readonly records: RecordStore<T>;
140
+ readonly schemaMetadata: SchemaMetadataStore;
141
+ }
142
+
143
+ /**
144
+ * Transaction context with explicit reentrancy. Calling `withTransaction` on
145
+ * this context joins the ambient transaction; it never opens a nested one.
146
+ * Keep repository composition on this scoped value rather than re-entering a
147
+ * root store.
148
+ */
149
+ export interface ReentrantStorageTransaction<T extends StoredRecord>
150
+ extends StorageTransaction<T>, Transaction<ReentrantStorageTransaction<T>> {}
151
+
152
+ /** Composite store contract used by adapters with an explicit lifecycle. */
153
+ export interface TransactionalStorageStore<T extends StoredRecord>
154
+ extends StorageTransaction<T>, Transaction<ReentrantStorageTransaction<T>> {
155
+ /**
156
+ * Waits for already-started transactions and closes the adapter. After it
157
+ * resolves, every operation fails with `StorageError.code === "storage_closed"`.
158
+ */
159
+ close(): Promise<void>;
160
+ }