@baukit/data-contracts 0.1.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.
- package/LICENSE +21 -0
- package/README.md +99 -0
- package/dist/contracts.d.ts +104 -0
- package/dist/contracts.d.ts.map +1 -0
- package/dist/contracts.js +34 -0
- package/dist/contracts.js.map +1 -0
- package/dist/erasure.d.ts +50 -0
- package/dist/erasure.d.ts.map +1 -0
- package/dist/erasure.js +107 -0
- package/dist/erasure.js.map +1 -0
- package/dist/identity.d.ts +122 -0
- package/dist/identity.d.ts.map +1 -0
- package/dist/identity.js +424 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/memory.d.ts +70 -0
- package/dist/memory.d.ts.map +1 -0
- package/dist/memory.js +283 -0
- package/dist/memory.js.map +1 -0
- package/dist/vitest.d.ts +32 -0
- package/dist/vitest.d.ts.map +1 -0
- package/dist/vitest.js +484 -0
- package/dist/vitest.js.map +1 -0
- package/package.json +49 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Patrick Koss
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# `@baukit/data-contracts`
|
|
2
|
+
|
|
3
|
+
Provider-neutral, asynchronous storage contracts plus executable adapter conformance tests.
|
|
4
|
+
|
|
5
|
+
The package defines JSON key/value storage, ID-ordered record storage with bounded keyset pagination, atomic transaction callbacks, and schema metadata/migration conventions. It deliberately contains no product entities and no Expo SQLite, Dexie, or Node database adapters.
|
|
6
|
+
|
|
7
|
+
## Using the contracts
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import type { StoredRecord, TransactionalStorageStore } from '@baukit/data-contracts';
|
|
11
|
+
|
|
12
|
+
interface Note extends StoredRecord {
|
|
13
|
+
title: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
type NoteDatabase = TransactionalStorageStore<Note>;
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`TransactionalStorageStore` makes nesting and lifecycle behavior explicit.
|
|
20
|
+
Inside a callback, call `withTransaction` on the transaction-scoped context to
|
|
21
|
+
join the ambient transaction. Calls on the root store are independent and must
|
|
22
|
+
be serialized by the adapter. After `close()` resolves, all operations reject
|
|
23
|
+
with `StorageError.code === "storage_closed"`. Quota failures use
|
|
24
|
+
`storage_quota_exceeded`; callers never need to parse provider error text.
|
|
25
|
+
|
|
26
|
+
The older `StorageTransaction` and `Transaction` interfaces remain available
|
|
27
|
+
for adapters that implement only the original surface.
|
|
28
|
+
|
|
29
|
+
## Authenticated partitions
|
|
30
|
+
|
|
31
|
+
`deriveScopedStoreName(namespace, subject)` hashes a length-delimited canonical
|
|
32
|
+
identity with SHA-256 and returns an opaque name. Browser and Node runtimes use
|
|
33
|
+
`globalThis.crypto.subtle`. React Native must install a standards-compatible
|
|
34
|
+
Web Crypto polyfill before calling the default helper, or inject a
|
|
35
|
+
`ScopedPersistenceDigest`; the generated Expo template injects `expo-crypto`.
|
|
36
|
+
|
|
37
|
+
Keep `ScopedPersistenceRegistryStore` outside the domain database (for example,
|
|
38
|
+
SecureStore or localStorage). `resolveScopedStore` serializes access through one
|
|
39
|
+
registry instance, validates all versioned metadata, and only claims a legacy
|
|
40
|
+
store when an explicit inspector returns `claimable` or `current-subject`.
|
|
41
|
+
Malformed, unknown-version, inconsistent, or digest-mismatched metadata throws
|
|
42
|
+
`PersistenceIdentityMismatchError` with code
|
|
43
|
+
`persistence_identity_mismatch` before a domain store is opened.
|
|
44
|
+
Keep the configured legacy store name available after a successful claim: every
|
|
45
|
+
reopen verifies the recorded name against that configuration and fails closed
|
|
46
|
+
if it is missing or changed. A store name may belong to only one registry entry,
|
|
47
|
+
including across namespaces.
|
|
48
|
+
|
|
49
|
+
`ScopedPersistenceLifecycle` immediately hides stale handles, closes before it
|
|
50
|
+
opens another subject, resets product-provided user-scoped memory, and publishes
|
|
51
|
+
only an open/migrated/hydrated partition. Call `handleSessionExpired()` for a
|
|
52
|
+
terminal authentication expiry; it closes and blocks without inventing a
|
|
53
|
+
subject switch. Products with an older, already-versioned ownership registry
|
|
54
|
+
may supply `resolveStore` to retain those database names while adopting the
|
|
55
|
+
shared close/reset/publish lifecycle. The compatibility resolver remains
|
|
56
|
+
responsible for validating its legacy metadata and failing closed. Use
|
|
57
|
+
`recheckServerSubjectBeforeSyncAdoption` immediately before server identity
|
|
58
|
+
adoption or an outbox push.
|
|
59
|
+
|
|
60
|
+
`RecordStore.list` orders immutable string IDs ascending using JavaScript string comparison. Page sizes are limited to `1..MAX_PAGE_SIZE`, and continuation cursors must be opaque to callers. Adapters should implement keyset cursors based on the last returned ID, not numeric offsets, so insertion before a cursor cannot shift later pages.
|
|
61
|
+
|
|
62
|
+
## Proving an adapter
|
|
63
|
+
|
|
64
|
+
Vitest helpers are isolated in a test-only subpath. Vitest is deliberately not a peer dependency, so it is never installed in Jest or production consumers. Install Vitest in an adapter project's development dependencies before importing the subpath, then register the applicable suites:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
import {
|
|
68
|
+
describeKeyValueContract,
|
|
69
|
+
describeRecordStoreContract,
|
|
70
|
+
describeSchemaMetadataContract,
|
|
71
|
+
describeScopedPersistenceContract,
|
|
72
|
+
describeTransactionContract,
|
|
73
|
+
describeTransactionalStorageContract,
|
|
74
|
+
} from '@baukit/data-contracts/vitest';
|
|
75
|
+
|
|
76
|
+
const makeDatabase = () => new MyAdapter();
|
|
77
|
+
|
|
78
|
+
describeKeyValueContract(() => makeDatabase().keyValues);
|
|
79
|
+
describeRecordStoreContract(() => makeDatabase().records);
|
|
80
|
+
describeTransactionContract(makeDatabase);
|
|
81
|
+
describeTransactionalStorageContract(makeDatabase);
|
|
82
|
+
describeScopedPersistenceContract(makeNamedDatabaseAdapter);
|
|
83
|
+
describeSchemaMetadataContract(() => makeDatabase().schemaMetadata);
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Each factory must return a fresh, empty store. The record suite supplies its
|
|
87
|
+
own JSON-shaped `{ id, label, payload }` records. A transaction implementation
|
|
88
|
+
must expose a callback-scoped view and make all callback writes visible
|
|
89
|
+
together, or none if the callback throws/rejects. The stronger composite suite
|
|
90
|
+
also proves callback results, compound and write-plus-outbox-shaped atomicity,
|
|
91
|
+
joined reentrancy, quota normalization, close behavior, and concurrent
|
|
92
|
+
transaction serialization. The scoped suite proves offline E→F→E record and
|
|
93
|
+
outbox isolation, close-before-open ordering, memory reset, legacy claims,
|
|
94
|
+
corrupt-registry blocking, server-subject checks, and terminal expiry. Its
|
|
95
|
+
adapter factory must reopen the same durable data for the same name. The
|
|
96
|
+
included `InMemoryStore` exposes `keyValues`,
|
|
97
|
+
`records`, and `schemaMetadata` namespaces and is itself tested by every suite.
|
|
98
|
+
|
|
99
|
+
Persistence adapters and product-specific migration logic belong in product or future adapter packages. The production entry point has no runtime dependencies; only the `/vitest` subpath expects the consumer's Vitest installation.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/** A value that can be represented without loss by JSON. */
|
|
2
|
+
export type JsonPrimitive = boolean | number | string | null;
|
|
3
|
+
/** A recursively JSON-serializable value. */
|
|
4
|
+
export type JsonValue = JsonPrimitive | JsonValue[] | {
|
|
5
|
+
[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
|
+
/** Records use an immutable string ID as their stable ordering and lookup key. */
|
|
17
|
+
export interface StoredRecord {
|
|
18
|
+
readonly id: string;
|
|
19
|
+
}
|
|
20
|
+
/** An opaque continuation token returned by a previous `list` call. */
|
|
21
|
+
export type Cursor = string;
|
|
22
|
+
export interface PageOptions {
|
|
23
|
+
/** Omit (or pass `null`) to begin at the first record. */
|
|
24
|
+
readonly cursor?: Cursor | null;
|
|
25
|
+
/** Must be an integer between 1 and `MAX_PAGE_SIZE`, inclusive. */
|
|
26
|
+
readonly limit?: number;
|
|
27
|
+
}
|
|
28
|
+
/** A cursor page. A null cursor means the page is terminal. */
|
|
29
|
+
export interface Page<T> {
|
|
30
|
+
readonly items: readonly T[];
|
|
31
|
+
readonly nextCursor: Cursor | null;
|
|
32
|
+
}
|
|
33
|
+
export declare const DEFAULT_PAGE_SIZE = 50;
|
|
34
|
+
export declare const MAX_PAGE_SIZE = 100;
|
|
35
|
+
/**
|
|
36
|
+
* A record store ordered by immutable `id`, ascending by JavaScript string
|
|
37
|
+
* comparison. Cursors are keyset positions: inserts before a returned cursor
|
|
38
|
+
* never shift or duplicate later pages.
|
|
39
|
+
*/
|
|
40
|
+
export interface RecordStore<T extends StoredRecord> {
|
|
41
|
+
/** Inserts or replaces the record with the same ID. */
|
|
42
|
+
put(record: T): Promise<void>;
|
|
43
|
+
/** Returns `undefined` when the ID does not exist. */
|
|
44
|
+
get(id: string): Promise<T | undefined>;
|
|
45
|
+
/** Deletes a record if present. Deleting a missing ID is a no-op. */
|
|
46
|
+
delete(id: string): Promise<void>;
|
|
47
|
+
list(options?: PageOptions): Promise<Page<T>>;
|
|
48
|
+
}
|
|
49
|
+
/** Portable schema identity persisted alongside adapter data. */
|
|
50
|
+
export interface SchemaMeta {
|
|
51
|
+
readonly name: string;
|
|
52
|
+
/** A non-negative integer incremented for every schema change. */
|
|
53
|
+
readonly version: number;
|
|
54
|
+
}
|
|
55
|
+
export interface SchemaMetadataStore {
|
|
56
|
+
/** Returns `undefined` before metadata is initialized. */
|
|
57
|
+
getSchemaMeta(): Promise<SchemaMeta | undefined>;
|
|
58
|
+
setSchemaMeta(metadata: SchemaMeta): Promise<void>;
|
|
59
|
+
}
|
|
60
|
+
/** A product-provided hook used to move between two schema identities. */
|
|
61
|
+
export interface SchemaMigrationHook {
|
|
62
|
+
migrate(from: SchemaMeta, to: SchemaMeta): Promise<void>;
|
|
63
|
+
}
|
|
64
|
+
export type MaybePromise<T> = Promise<T> | T;
|
|
65
|
+
/** Stable machine-readable failures shared by storage adapters. */
|
|
66
|
+
export type StorageErrorCode = 'storage_closed' | 'storage_quota_exceeded';
|
|
67
|
+
/** A provider-neutral storage failure safe to branch on without parsing text. */
|
|
68
|
+
export declare class StorageError extends Error {
|
|
69
|
+
readonly code: StorageErrorCode;
|
|
70
|
+
readonly name = "StorageError";
|
|
71
|
+
constructor(code: StorageErrorCode, message: string, options?: ErrorOptions);
|
|
72
|
+
}
|
|
73
|
+
/** Returns quota failures from nested adapter errors as one stable error. */
|
|
74
|
+
export declare function normalizeStorageError(cause: unknown): unknown;
|
|
75
|
+
/**
|
|
76
|
+
* Executes work against a transaction-scoped context. If the callback throws
|
|
77
|
+
* or rejects, none of its writes become visible. Its return value is preserved.
|
|
78
|
+
*/
|
|
79
|
+
export interface Transaction<TContext> {
|
|
80
|
+
withTransaction<TResult>(operation: (context: TContext) => MaybePromise<TResult>): Promise<TResult>;
|
|
81
|
+
}
|
|
82
|
+
/** The standard transaction view used by composite storage adapters. */
|
|
83
|
+
export interface StorageTransaction<T extends StoredRecord> {
|
|
84
|
+
readonly keyValues: KeyValueStore;
|
|
85
|
+
readonly records: RecordStore<T>;
|
|
86
|
+
readonly schemaMetadata: SchemaMetadataStore;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Transaction context with explicit reentrancy. Calling `withTransaction` on
|
|
90
|
+
* this context joins the ambient transaction; it never opens a nested one.
|
|
91
|
+
* Keep repository composition on this scoped value rather than re-entering a
|
|
92
|
+
* root store.
|
|
93
|
+
*/
|
|
94
|
+
export interface ReentrantStorageTransaction<T extends StoredRecord> extends StorageTransaction<T>, Transaction<ReentrantStorageTransaction<T>> {
|
|
95
|
+
}
|
|
96
|
+
/** Composite store contract used by adapters with an explicit lifecycle. */
|
|
97
|
+
export interface TransactionalStorageStore<T extends StoredRecord> extends StorageTransaction<T>, Transaction<ReentrantStorageTransaction<T>> {
|
|
98
|
+
/**
|
|
99
|
+
* Waits for already-started transactions and closes the adapter. After it
|
|
100
|
+
* resolves, every operation fails with `StorageError.code === "storage_closed"`.
|
|
101
|
+
*/
|
|
102
|
+
close(): Promise<void>;
|
|
103
|
+
}
|
|
104
|
+
//# sourceMappingURL=contracts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE7D,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnF,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,mEAAmE;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,uEAAuE;AACvE,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,YAAY;IACjD,uDAAuD;IACvD,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,sDAAsD;IACtD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACxC,qEAAqE;IACrE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,aAAa,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IACjD,aAAa,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAE7C,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,wBAAwB,CAAC;AAE3E,iFAAiF;AACjF,qBAAa,YAAa,SAAQ,KAAK;aAInB,IAAI,EAAE,gBAAgB;IAHxC,SAAyB,IAAI,kBAAkB;gBAG7B,IAAI,EAAE,gBAAgB,EACtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIzB;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAkB7D;AAUD;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ;IACnC,eAAe,CAAC,OAAO,EACrB,SAAS,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,YAAY,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,YAAY;IACxD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,YAAY,CACjE,SAAQ,kBAAkB,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC;CAAG;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,YAAY,CAC/D,SAAQ,kBAAkB,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC;IAC1E;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
export const DEFAULT_PAGE_SIZE = 50;
|
|
2
|
+
export const MAX_PAGE_SIZE = 100;
|
|
3
|
+
/** A provider-neutral storage failure safe to branch on without parsing text. */
|
|
4
|
+
export class StorageError extends Error {
|
|
5
|
+
code;
|
|
6
|
+
name = 'StorageError';
|
|
7
|
+
constructor(code, message, options) {
|
|
8
|
+
super(message, options);
|
|
9
|
+
this.code = code;
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
/** Returns quota failures from nested adapter errors as one stable error. */
|
|
13
|
+
export function normalizeStorageError(cause) {
|
|
14
|
+
if (cause instanceof StorageError) {
|
|
15
|
+
return cause;
|
|
16
|
+
}
|
|
17
|
+
let candidate = cause;
|
|
18
|
+
const visited = new Set();
|
|
19
|
+
while (candidate !== null && candidate !== undefined && !visited.has(candidate)) {
|
|
20
|
+
visited.add(candidate);
|
|
21
|
+
if (errorField(candidate, 'name') === 'QuotaExceededError') {
|
|
22
|
+
return new StorageError('storage_quota_exceeded', 'Storage quota was exceeded; the write was not saved.', { cause });
|
|
23
|
+
}
|
|
24
|
+
candidate = nestedError(candidate);
|
|
25
|
+
}
|
|
26
|
+
return cause;
|
|
27
|
+
}
|
|
28
|
+
function errorField(error, field) {
|
|
29
|
+
return typeof error === 'object' && error !== null ? Reflect.get(error, field) : undefined;
|
|
30
|
+
}
|
|
31
|
+
function nestedError(error) {
|
|
32
|
+
return errorField(error, 'cause') ?? errorField(error, 'inner');
|
|
33
|
+
}
|
|
34
|
+
//# sourceMappingURL=contracts.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAqCA,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAwCjC,iFAAiF;AACjF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAInB;IAHO,IAAI,GAAG,cAAc,CAAC;IAE/C,YACkB,IAAsB,EACtC,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAJR,SAAI,GAAJ,IAAI,CAAkB;IAKxC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,GAAY,KAAK,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAW,CAAC;IACnC,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAChF,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,IAAI,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,oBAAoB,EAAE,CAAC;YAC3D,OAAO,IAAI,YAAY,CACrB,wBAAwB,EACxB,sDAAsD,EACtD,EAAE,KAAK,EAAE,CACV,CAAC;QACJ,CAAC;QACD,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,KAAa;IAC/C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/** Receipt returned after the server accepts or completes product-profile erasure. */
|
|
2
|
+
export type ErasureReceipt = {
|
|
3
|
+
readonly operationId: string | null;
|
|
4
|
+
readonly status: 'completed';
|
|
5
|
+
} | {
|
|
6
|
+
readonly operationId: string;
|
|
7
|
+
readonly status: 'pending';
|
|
8
|
+
};
|
|
9
|
+
/** Dependencies for the product-profile erasure sequence. */
|
|
10
|
+
export interface ProductProfileErasureDependencies {
|
|
11
|
+
readonly beforeServerErase?: readonly (() => Promise<void>)[];
|
|
12
|
+
readonly eraseServerProfile: () => Promise<ErasureReceipt>;
|
|
13
|
+
readonly eraseLocalPartition: () => Promise<void>;
|
|
14
|
+
readonly signOut: () => Promise<void>;
|
|
15
|
+
}
|
|
16
|
+
export type ProductProfileErasureStage = 'before-server' | 'server' | 'local' | 'sign-out';
|
|
17
|
+
/** Error detail safe to show in diagnostics without user or request content. */
|
|
18
|
+
export interface ProductProfileErasureIssue {
|
|
19
|
+
readonly stage: ProductProfileErasureStage;
|
|
20
|
+
readonly cause: string;
|
|
21
|
+
}
|
|
22
|
+
export type ProductProfileErasureResult = {
|
|
23
|
+
readonly status: 'erased';
|
|
24
|
+
readonly receipt: ErasureReceipt;
|
|
25
|
+
readonly warnings: readonly ProductProfileErasureIssue[];
|
|
26
|
+
} | {
|
|
27
|
+
readonly status: 'server-failure' | 'ambiguous';
|
|
28
|
+
readonly error: ProductProfileErasureIssue;
|
|
29
|
+
readonly warnings: readonly ProductProfileErasureIssue[];
|
|
30
|
+
} | {
|
|
31
|
+
readonly status: 'local-failure';
|
|
32
|
+
readonly receipt: ErasureReceipt;
|
|
33
|
+
readonly error: ProductProfileErasureIssue;
|
|
34
|
+
readonly signOutError: ProductProfileErasureIssue | null;
|
|
35
|
+
readonly warnings: readonly ProductProfileErasureIssue[];
|
|
36
|
+
} | {
|
|
37
|
+
readonly status: 'signout-failure';
|
|
38
|
+
readonly receipt: ErasureReceipt;
|
|
39
|
+
readonly error: ProductProfileErasureIssue;
|
|
40
|
+
readonly warnings: readonly ProductProfileErasureIssue[];
|
|
41
|
+
};
|
|
42
|
+
/** Marks a server error whose commit status cannot be determined safely. */
|
|
43
|
+
export declare class AmbiguousProductProfileErasureError extends Error {
|
|
44
|
+
readonly name = "AmbiguousProductProfileErasureError";
|
|
45
|
+
readonly code: "product_profile_erasure_ambiguous";
|
|
46
|
+
constructor(cause?: unknown);
|
|
47
|
+
}
|
|
48
|
+
/** Erases a product profile while preserving retryability at the server boundary. */
|
|
49
|
+
export declare function eraseProductProfile(dependencies: ProductProfileErasureDependencies): Promise<ProductProfileErasureResult>;
|
|
50
|
+
//# sourceMappingURL=erasure.d.ts.map
|
|
@@ -0,0 +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,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjE,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,CAAC;IAC1B,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/dist/erasure.js
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/** Marks a server error whose commit status cannot be determined safely. */
|
|
2
|
+
export class AmbiguousProductProfileErasureError extends Error {
|
|
3
|
+
name = 'AmbiguousProductProfileErasureError';
|
|
4
|
+
code = 'product_profile_erasure_ambiguous';
|
|
5
|
+
constructor(cause) {
|
|
6
|
+
super('The server erasure outcome is unknown.', cause === undefined ? undefined : { cause });
|
|
7
|
+
}
|
|
8
|
+
}
|
|
9
|
+
const SAFE_CAUSE_NAMES = new Set([
|
|
10
|
+
'AbortError',
|
|
11
|
+
'AggregateError',
|
|
12
|
+
'Error',
|
|
13
|
+
'EvalError',
|
|
14
|
+
'NetworkError',
|
|
15
|
+
'RangeError',
|
|
16
|
+
'ReferenceError',
|
|
17
|
+
'SyntaxError',
|
|
18
|
+
'TimeoutError',
|
|
19
|
+
'TypeError',
|
|
20
|
+
'URIError',
|
|
21
|
+
]);
|
|
22
|
+
function causeName(cause) {
|
|
23
|
+
if (!(cause instanceof Error))
|
|
24
|
+
return 'UnknownError';
|
|
25
|
+
return SAFE_CAUSE_NAMES.has(cause.name) ? cause.name : 'Error';
|
|
26
|
+
}
|
|
27
|
+
function issue(stage, cause) {
|
|
28
|
+
return { stage, cause: causeName(cause) };
|
|
29
|
+
}
|
|
30
|
+
function isAmbiguous(cause) {
|
|
31
|
+
return (cause instanceof AmbiguousProductProfileErasureError ||
|
|
32
|
+
(typeof cause === 'object' &&
|
|
33
|
+
cause !== null &&
|
|
34
|
+
Reflect.get(cause, 'code') === 'product_profile_erasure_ambiguous'));
|
|
35
|
+
}
|
|
36
|
+
function ambiguousCause(cause) {
|
|
37
|
+
if (cause instanceof Error && cause.cause !== undefined)
|
|
38
|
+
return cause.cause;
|
|
39
|
+
return cause;
|
|
40
|
+
}
|
|
41
|
+
function validateErasureReceipt(receipt) {
|
|
42
|
+
if (typeof receipt !== 'object' || receipt === null) {
|
|
43
|
+
throw new AmbiguousProductProfileErasureError(new TypeError('Invalid erasure receipt.'));
|
|
44
|
+
}
|
|
45
|
+
const operationId = Reflect.get(receipt, 'operationId');
|
|
46
|
+
const status = Reflect.get(receipt, 'status');
|
|
47
|
+
const hasOperationId = typeof operationId === 'string' && operationId.trim().length > 0;
|
|
48
|
+
if ((status === 'completed' && (operationId === null || hasOperationId)) ||
|
|
49
|
+
(status === 'pending' && hasOperationId)) {
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
throw new AmbiguousProductProfileErasureError(new TypeError('Invalid erasure receipt.'));
|
|
53
|
+
}
|
|
54
|
+
/** Erases a product profile while preserving retryability at the server boundary. */
|
|
55
|
+
export async function eraseProductProfile(dependencies) {
|
|
56
|
+
const warnings = [];
|
|
57
|
+
for (const hook of dependencies.beforeServerErase ?? []) {
|
|
58
|
+
try {
|
|
59
|
+
await hook();
|
|
60
|
+
}
|
|
61
|
+
catch (cause) {
|
|
62
|
+
warnings.push(issue('before-server', cause));
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
let receipt;
|
|
66
|
+
try {
|
|
67
|
+
const candidate = await dependencies.eraseServerProfile();
|
|
68
|
+
validateErasureReceipt(candidate);
|
|
69
|
+
receipt = candidate;
|
|
70
|
+
}
|
|
71
|
+
catch (cause) {
|
|
72
|
+
if (isAmbiguous(cause)) {
|
|
73
|
+
return { status: 'ambiguous', error: issue('server', ambiguousCause(cause)), warnings };
|
|
74
|
+
}
|
|
75
|
+
return { status: 'server-failure', error: issue('server', cause), warnings };
|
|
76
|
+
}
|
|
77
|
+
let localError;
|
|
78
|
+
let signOutError;
|
|
79
|
+
try {
|
|
80
|
+
await dependencies.eraseLocalPartition();
|
|
81
|
+
}
|
|
82
|
+
catch (cause) {
|
|
83
|
+
localError = issue('local', cause);
|
|
84
|
+
}
|
|
85
|
+
finally {
|
|
86
|
+
try {
|
|
87
|
+
await dependencies.signOut();
|
|
88
|
+
}
|
|
89
|
+
catch (cause) {
|
|
90
|
+
signOutError = issue('sign-out', cause);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
if (localError !== undefined) {
|
|
94
|
+
return {
|
|
95
|
+
status: 'local-failure',
|
|
96
|
+
receipt,
|
|
97
|
+
error: localError,
|
|
98
|
+
signOutError: signOutError ?? null,
|
|
99
|
+
warnings,
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
if (signOutError !== undefined) {
|
|
103
|
+
return { status: 'signout-failure', receipt, error: signOutError, warnings };
|
|
104
|
+
}
|
|
105
|
+
return { status: 'erased', receipt, warnings };
|
|
106
|
+
}
|
|
107
|
+
//# sourceMappingURL=erasure.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"erasure.js","sourceRoot":"","sources":["../src/erasure.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import type { MaybePromise } from './contracts.js';
|
|
2
|
+
/** Product-selected behavior for a partition after logout. */
|
|
3
|
+
export type LocalDataRetention = 'retain' | 'delete' | 'quarantine';
|
|
4
|
+
/** Registry persistence kept outside the user-owned domain database. */
|
|
5
|
+
export interface ScopedPersistenceRegistryStore {
|
|
6
|
+
read(): Promise<string | null>;
|
|
7
|
+
write(serialized: string): Promise<void>;
|
|
8
|
+
}
|
|
9
|
+
/** A digest seam for runtimes that install their Web Crypto implementation explicitly. */
|
|
10
|
+
export type ScopedPersistenceDigest = (value: string) => Promise<string>;
|
|
11
|
+
export type LegacyStoreOwnership = 'claimable' | 'current-subject' | 'other-subject' | 'ambiguous';
|
|
12
|
+
export type LegacyStoreInspection = {
|
|
13
|
+
readonly exists: false;
|
|
14
|
+
} | {
|
|
15
|
+
readonly exists: true;
|
|
16
|
+
readonly ownership: LegacyStoreOwnership;
|
|
17
|
+
};
|
|
18
|
+
export interface ResolveScopedStoreOptions {
|
|
19
|
+
readonly namespace: string;
|
|
20
|
+
readonly subject: string;
|
|
21
|
+
readonly registry: ScopedPersistenceRegistryStore;
|
|
22
|
+
readonly digest?: ScopedPersistenceDigest;
|
|
23
|
+
readonly inspectLegacy?: (subject: string) => Promise<LegacyStoreInspection>;
|
|
24
|
+
readonly legacyStoreName?: string;
|
|
25
|
+
}
|
|
26
|
+
export interface ResolvedScopedStore {
|
|
27
|
+
readonly storeName: string;
|
|
28
|
+
readonly claimedLegacy: boolean;
|
|
29
|
+
}
|
|
30
|
+
/** Product compatibility resolver used when older ownership metadata already exists. */
|
|
31
|
+
export type ScopedPersistenceResolver = (subject: string) => MaybePromise<ResolvedScopedStore>;
|
|
32
|
+
/** Stable blocking failure for corrupt ownership metadata or a subject mismatch. */
|
|
33
|
+
export declare class PersistenceIdentityMismatchError extends Error {
|
|
34
|
+
readonly name = "PersistenceIdentityMismatchError";
|
|
35
|
+
readonly code: "persistence_identity_mismatch";
|
|
36
|
+
constructor(message?: string, options?: ErrorOptions);
|
|
37
|
+
}
|
|
38
|
+
export declare function isPersistenceIdentityMismatchError(cause: unknown): cause is PersistenceIdentityMismatchError;
|
|
39
|
+
/** Small deterministic registry adapter for tests and non-persistent products. */
|
|
40
|
+
export declare class InMemoryScopedPersistenceRegistryStore implements ScopedPersistenceRegistryStore {
|
|
41
|
+
private serialized;
|
|
42
|
+
constructor(serialized?: string | null);
|
|
43
|
+
read(): Promise<string | null>;
|
|
44
|
+
write(serialized: string): Promise<void>;
|
|
45
|
+
}
|
|
46
|
+
/** Derives an opaque, stable name without disclosing the namespace or OIDC subject. */
|
|
47
|
+
export declare function deriveScopedStoreName(namespace: string, subject: string, digest?: ScopedPersistenceDigest): Promise<string>;
|
|
48
|
+
/** Resolves or atomically records one authenticated subject's local partition. */
|
|
49
|
+
export declare function resolveScopedStore(options: ResolveScopedStoreOptions): Promise<ResolvedScopedStore>;
|
|
50
|
+
export interface RemoveScopedPersistenceRegistryEntryOptions {
|
|
51
|
+
readonly namespace: string;
|
|
52
|
+
readonly subject: string;
|
|
53
|
+
readonly registry: ScopedPersistenceRegistryStore;
|
|
54
|
+
}
|
|
55
|
+
/** Removes one subject mapping without exposing serialized registry metadata. */
|
|
56
|
+
export declare function removeScopedPersistenceRegistryEntry(options: RemoveScopedPersistenceRegistryEntryOptions): Promise<boolean>;
|
|
57
|
+
export interface ClosableScopedPersistence {
|
|
58
|
+
close(): Promise<void>;
|
|
59
|
+
}
|
|
60
|
+
export interface OpenScopedPersistenceContext {
|
|
61
|
+
readonly subject: string;
|
|
62
|
+
readonly storeName: string;
|
|
63
|
+
}
|
|
64
|
+
export interface ScopedPersistencePartition<TPersistence extends ClosableScopedPersistence> extends OpenScopedPersistenceContext {
|
|
65
|
+
readonly persistence: TPersistence;
|
|
66
|
+
}
|
|
67
|
+
export type ScopedPersistenceLifecycleState<TPersistence extends ClosableScopedPersistence> = {
|
|
68
|
+
readonly status: 'signed-out';
|
|
69
|
+
} | {
|
|
70
|
+
readonly status: 'initializing';
|
|
71
|
+
readonly subject: string;
|
|
72
|
+
} | {
|
|
73
|
+
readonly status: 'ready';
|
|
74
|
+
readonly partition: ScopedPersistencePartition<TPersistence>;
|
|
75
|
+
} | {
|
|
76
|
+
readonly status: 'blocked';
|
|
77
|
+
readonly reason: 'identity-mismatch' | 'initialization-failed' | 'session-expired';
|
|
78
|
+
readonly error: Error;
|
|
79
|
+
};
|
|
80
|
+
export interface ScopedPersistenceLifecycleOptions<TPersistence extends ClosableScopedPersistence> extends Omit<ResolveScopedStoreOptions, 'subject'> {
|
|
81
|
+
/** Overrides registry resolution while retaining lifecycle transition guarantees. */
|
|
82
|
+
readonly resolveStore?: ScopedPersistenceResolver;
|
|
83
|
+
readonly open: (context: OpenScopedPersistenceContext) => Promise<TPersistence>;
|
|
84
|
+
/** Deletes a closed persistence partition. Required by eraseActivePartition. */
|
|
85
|
+
readonly erase?: (context: OpenScopedPersistenceContext) => Promise<void>;
|
|
86
|
+
readonly resetUserScopedState: () => MaybePromise<void>;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Serializes identity transitions, hides stale handles immediately, and only
|
|
90
|
+
* publishes a partition after the product's open/migrate/hydrate hook resolves.
|
|
91
|
+
*/
|
|
92
|
+
export declare class ScopedPersistenceLifecycle<TPersistence extends ClosableScopedPersistence> {
|
|
93
|
+
private readonly options;
|
|
94
|
+
private activePartition;
|
|
95
|
+
private transitionTail;
|
|
96
|
+
private revision;
|
|
97
|
+
private lifecycleState;
|
|
98
|
+
constructor(options: ScopedPersistenceLifecycleOptions<TPersistence>);
|
|
99
|
+
get state(): ScopedPersistenceLifecycleState<TPersistence>;
|
|
100
|
+
/** Returns no persistence while a transition is pending or blocked. */
|
|
101
|
+
current(): ScopedPersistencePartition<TPersistence> | undefined;
|
|
102
|
+
selectSubject(subject: string): Promise<ScopedPersistencePartition<TPersistence> | undefined>;
|
|
103
|
+
clear(): Promise<void>;
|
|
104
|
+
/** Closes and deletes the active partition, then removes its registry mapping. */
|
|
105
|
+
eraseActivePartition(): Promise<boolean>;
|
|
106
|
+
/** Terminal auth expiry closes the current partition and remains blocked. */
|
|
107
|
+
handleSessionExpired(): Promise<void>;
|
|
108
|
+
/** Blocks an already-open partition after a server subject recheck fails. */
|
|
109
|
+
blockIdentityMismatch(error: PersistenceIdentityMismatchError): Promise<void>;
|
|
110
|
+
private enqueue;
|
|
111
|
+
private selectSubjectLocked;
|
|
112
|
+
private closeAndReset;
|
|
113
|
+
private closePartitionAndReset;
|
|
114
|
+
}
|
|
115
|
+
export interface RecheckServerSubjectOptions<TResult> {
|
|
116
|
+
readonly partitionSubject: string;
|
|
117
|
+
readonly readServerSubject: () => Promise<string>;
|
|
118
|
+
readonly adopt: () => MaybePromise<TResult>;
|
|
119
|
+
}
|
|
120
|
+
/** Performs the final subject check before sync adoption or an outbox push. */
|
|
121
|
+
export declare function recheckServerSubjectBeforeSyncAdoption<TResult>(options: RecheckServerSubjectOptions<TResult>): Promise<TResult>;
|
|
122
|
+
//# sourceMappingURL=identity.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}
|