@sdux-vault/shared 0.0.10
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 +249 -0
- package/README.md +258 -0
- package/fesm2022/sdux-vault-shared.mjs +1256 -0
- package/fesm2022/sdux-vault-shared.mjs.map +1 -0
- package/package.json +47 -0
- package/types/sdux-vault-shared.d.ts +1801 -0
|
@@ -0,0 +1,1801 @@
|
|
|
1
|
+
import { Observable, Subject } from 'rxjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Extends the global Window object with optional SDuX monitoring and DevTools references.
|
|
5
|
+
* This declaration defines the global attachment points used to expose runtime singletons.
|
|
6
|
+
*/
|
|
7
|
+
declare global {
|
|
8
|
+
interface Window {
|
|
9
|
+
/**
|
|
10
|
+
* Optional container for globally exposed SDuX runtime instances.
|
|
11
|
+
*/
|
|
12
|
+
sdux?: SDuXShape;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Optional global reference to SDuX runtime instances.
|
|
16
|
+
*/
|
|
17
|
+
var sdux: SDuXShape | undefined;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
interface BehaviorClassContext {
|
|
21
|
+
/**
|
|
22
|
+
* The unique key of the FeatureCell that this behavior instance is
|
|
23
|
+
* operating within. Used to scope behavior execution to a specific cell.
|
|
24
|
+
*/
|
|
25
|
+
readonly featureCellKey: string;
|
|
26
|
+
readonly behaviorConfig?: unknown;
|
|
27
|
+
readonly licensePayload?: unknown;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Canonical error representation emitted by the Vault pipeline.
|
|
32
|
+
*
|
|
33
|
+
* `VaultError` normalizes thrown values from any pipeline stage into a
|
|
34
|
+
* consistent shape that addon error behaviors can transform and that
|
|
35
|
+
* consumers can observe from the global VaultErrorPublicService signal.
|
|
36
|
+
*/
|
|
37
|
+
interface VaultErrorShape {
|
|
38
|
+
/**
|
|
39
|
+
* Human-readable error message.
|
|
40
|
+
*/
|
|
41
|
+
message: string;
|
|
42
|
+
/**
|
|
43
|
+
* Optional FeatureCell key.
|
|
44
|
+
*/
|
|
45
|
+
featureCellKey: string;
|
|
46
|
+
/**
|
|
47
|
+
* Timestamp (epoch ms) when the error occurred.
|
|
48
|
+
* Enables reactive timelines and differentiating repeated errors.
|
|
49
|
+
*/
|
|
50
|
+
timestamp: number;
|
|
51
|
+
/**
|
|
52
|
+
* Raw thrown value captured before any normalization.
|
|
53
|
+
* Useful for debugging, logging, and devtools visualization.
|
|
54
|
+
*/
|
|
55
|
+
raw: unknown;
|
|
56
|
+
/**
|
|
57
|
+
* Optional numeric status (HTTP or domain).
|
|
58
|
+
*/
|
|
59
|
+
status?: number;
|
|
60
|
+
/**
|
|
61
|
+
* Optional textual status text (e.g., HTTP status text).
|
|
62
|
+
*/
|
|
63
|
+
statusText?: string;
|
|
64
|
+
/**
|
|
65
|
+
* Additional diagnostic or domain-specific details.
|
|
66
|
+
*/
|
|
67
|
+
details?: unknown;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Defines the immutable snapshot shape representing FeatureCell state at a specific moment.
|
|
72
|
+
* This interface exposes loading, value, and error indicators used by consumers to reason about current state.
|
|
73
|
+
*
|
|
74
|
+
* --RelatedStart--
|
|
75
|
+
* VaultErrorShape
|
|
76
|
+
* --RelatedEnd--
|
|
77
|
+
*/
|
|
78
|
+
interface StateSnapshotShape<T> {
|
|
79
|
+
/**
|
|
80
|
+
* Indicates whether the state is currently in a loading phase.
|
|
81
|
+
*/
|
|
82
|
+
isLoading: boolean;
|
|
83
|
+
/**
|
|
84
|
+
* The resolved value for this snapshot, or `undefined` when no value exists.
|
|
85
|
+
*/
|
|
86
|
+
value: T | undefined;
|
|
87
|
+
/**
|
|
88
|
+
* Error associated with the state at this moment, or `null` if no error is present.
|
|
89
|
+
*/
|
|
90
|
+
error: VaultErrorShape | null;
|
|
91
|
+
/**
|
|
92
|
+
* Whether the snapshot contains a non-undefined value.
|
|
93
|
+
*/
|
|
94
|
+
hasValue: boolean;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Callback function signature used for observing errors emitted during
|
|
99
|
+
* the FeatureCell error-handling pipeline.
|
|
100
|
+
*
|
|
101
|
+
* An `ErrorCallback` receives the normalized {@link VaultErrorShape} produced by
|
|
102
|
+
* the pipeline and a read-only {@link StateSnapshotShape} representing the
|
|
103
|
+
* FeatureCell’s state at the time the error occurred.
|
|
104
|
+
*
|
|
105
|
+
* This callback type performs no transformation of the pipeline value;
|
|
106
|
+
* implementations are expected to execute side effects only, such as logging
|
|
107
|
+
* or reporting. Returning a value has no effect on pipeline behavior.
|
|
108
|
+
*
|
|
109
|
+
* @typeParam T - The type of the FeatureCell state associated with the callback.
|
|
110
|
+
*/
|
|
111
|
+
type VaultErrorCallback<T> = (error: VaultErrorShape, state: Readonly<StateSnapshotShape<T>>) => void;
|
|
112
|
+
|
|
113
|
+
declare const StateEmitTypes: {
|
|
114
|
+
readonly IncomingPipeline: "Incoming Pipeline";
|
|
115
|
+
readonly FinalizePipeline: "Finalize Pipeline";
|
|
116
|
+
readonly PipelineError: "Pipeline Error";
|
|
117
|
+
readonly PipelineDestroy: "Pipeline Destroy";
|
|
118
|
+
readonly PipelineReset: "Pipeline Reset";
|
|
119
|
+
readonly AbortController: "Abort Controller";
|
|
120
|
+
readonly DenyController: "Deny Controller";
|
|
121
|
+
};
|
|
122
|
+
type StateEmitType = (typeof StateEmitTypes)[keyof typeof StateEmitTypes];
|
|
123
|
+
|
|
124
|
+
interface StateEmitSnapshotShape<T> {
|
|
125
|
+
snapshot: StateSnapshotShape<T>;
|
|
126
|
+
options: unknown | undefined;
|
|
127
|
+
type: StateEmitType;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
declare const OperationTypes: {
|
|
131
|
+
readonly Merge: "merge";
|
|
132
|
+
readonly Replace: "replace";
|
|
133
|
+
readonly Initialize: "initialize";
|
|
134
|
+
};
|
|
135
|
+
type OperationType = (typeof OperationTypes)[keyof typeof OperationTypes];
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Enumerates the available resolve strategy identifiers used by resolve
|
|
139
|
+
* behaviors. These identifiers indicate how a FeatureCell obtains its initial
|
|
140
|
+
* and subsequent state values during the resolve stage of the pipeline.
|
|
141
|
+
*
|
|
142
|
+
* - `Value` — Resolve from a synchronous, in-memory value.
|
|
143
|
+
* - `HttpResource` — Resolve using an HTTP-driven resource behavior.
|
|
144
|
+
* - `Observable` — Resolve from an observable stream source.
|
|
145
|
+
* - `Promise` — Resolve from a promise source.
|
|
146
|
+
*/
|
|
147
|
+
declare const ResolveTypes: {
|
|
148
|
+
readonly HttpResource: "http-resource";
|
|
149
|
+
readonly Observable: "observable";
|
|
150
|
+
readonly Promise: "promise";
|
|
151
|
+
readonly Value: "value";
|
|
152
|
+
};
|
|
153
|
+
/**
|
|
154
|
+
* Union type representing all supported resolve strategy identifiers.
|
|
155
|
+
*/
|
|
156
|
+
type ResolveType = (typeof ResolveTypes)[keyof typeof ResolveTypes];
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Structural interface representing a reactive, asynchronously resolved resource.
|
|
160
|
+
*
|
|
161
|
+
* This interface intentionally mirrors the *shape* of Angular’s `HttpResourceRef`
|
|
162
|
+
* without introducing any framework dependency. It is used by core Vault logic
|
|
163
|
+
* to interact with resource-backed values in a fully framework-agnostic way.
|
|
164
|
+
*
|
|
165
|
+
* Implementations may be backed by:
|
|
166
|
+
* - Angular `HttpResourceRef`
|
|
167
|
+
* - Signals
|
|
168
|
+
* - Observables
|
|
169
|
+
* - Promises
|
|
170
|
+
* - Custom adapters or test doubles
|
|
171
|
+
*
|
|
172
|
+
* Consumers should treat all methods as **side-effect free** accessors.
|
|
173
|
+
*
|
|
174
|
+
* @typeParam T - The resolved value type of the resource.
|
|
175
|
+
*/
|
|
176
|
+
interface HttpResourceRefShape<T> {
|
|
177
|
+
/**
|
|
178
|
+
* Returns the current resolved value of the resource.
|
|
179
|
+
*
|
|
180
|
+
* - Returns `undefined` if the resource has not yet resolved
|
|
181
|
+
* - Returns a value of type `T` once available
|
|
182
|
+
*
|
|
183
|
+
* This method must be safe to call multiple times.
|
|
184
|
+
*/
|
|
185
|
+
value(): T | undefined;
|
|
186
|
+
/**
|
|
187
|
+
* Indicates whether the resource is currently loading.
|
|
188
|
+
*
|
|
189
|
+
* @returns `true` while the resource is resolving, otherwise `false`.
|
|
190
|
+
*/
|
|
191
|
+
isLoading(): boolean;
|
|
192
|
+
/**
|
|
193
|
+
* Returns the most recent error produced by the resource, if any.
|
|
194
|
+
*
|
|
195
|
+
* @returns An error object, or `null` / `undefined` if no error is present.
|
|
196
|
+
*/
|
|
197
|
+
error(): unknown;
|
|
198
|
+
/**
|
|
199
|
+
* Indicates whether the resource currently holds a resolved value.
|
|
200
|
+
*
|
|
201
|
+
* This is semantically equivalent to checking `value() !== undefined`,
|
|
202
|
+
* but is provided explicitly to support resource implementations that
|
|
203
|
+
* track resolution state independently.
|
|
204
|
+
*
|
|
205
|
+
* @returns `true` if a value is available, otherwise `false`.
|
|
206
|
+
*/
|
|
207
|
+
hasValue(): boolean;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
type DeferredType<T> = () => T | undefined | null | Promise<T | undefined | null>;
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Structured shape used to represent a state update packet flowing into the
|
|
214
|
+
* pipeline. Each field is optional, allowing callers to specify only the
|
|
215
|
+
* components of state they intend to update. This snapshot is interpreted by
|
|
216
|
+
* upstream behaviors including resolve, merge, filters, and reducers.
|
|
217
|
+
*
|
|
218
|
+
* @typeParam T - The underlying feature state value type.
|
|
219
|
+
*/
|
|
220
|
+
interface StateInputShape<T> {
|
|
221
|
+
/** Indicates whether the feature is currently loading. */
|
|
222
|
+
loading?: boolean;
|
|
223
|
+
/**
|
|
224
|
+
* The state value to apply. This may be the raw state value or the resolved
|
|
225
|
+
* upstream value type as defined by the pipeline.
|
|
226
|
+
*/
|
|
227
|
+
value?: T | undefined | null | DeferredType<T>;
|
|
228
|
+
/** Optional error information associated with the state update. */
|
|
229
|
+
error?: unknown;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
type DeferredFactory<T> = Partial<{
|
|
233
|
+
loading: boolean;
|
|
234
|
+
value: DeferredType<T>;
|
|
235
|
+
error: unknown;
|
|
236
|
+
}>;
|
|
237
|
+
|
|
238
|
+
type StateInputType<T> = T | StateInputShape<T> | DeferredFactory<T> | DeferredType<T> | HttpResourceRefShape<T> | Observable<T> | undefined | null;
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Defines the execution context supplied to behaviors during pipeline processing.
|
|
242
|
+
* This interface provides access to state snapshots, operation metadata, lifecycle signals, and configuration required for behavior execution.
|
|
243
|
+
*/
|
|
244
|
+
interface BehaviorContext<T> {
|
|
245
|
+
/**
|
|
246
|
+
* Emits when the FeatureCell is destroyed. Behaviors may subscribe to this
|
|
247
|
+
* to perform cleanup work.
|
|
248
|
+
*/
|
|
249
|
+
destroyed$?: Observable<void>;
|
|
250
|
+
/**
|
|
251
|
+
* The feature cell key
|
|
252
|
+
*/
|
|
253
|
+
featureCellKey: string;
|
|
254
|
+
/**
|
|
255
|
+
* The raw incoming payload submitted to the FeatureCell through replace or
|
|
256
|
+
* merge operations. This is the source input used by resolve and merge
|
|
257
|
+
* behaviors to compute next-state values.
|
|
258
|
+
*/
|
|
259
|
+
incoming?: StateInputType<T>;
|
|
260
|
+
/**
|
|
261
|
+
* The last snapshow of the state
|
|
262
|
+
*/
|
|
263
|
+
lastSnapshot: StateSnapshotShape<T>;
|
|
264
|
+
/**
|
|
265
|
+
* Indicates whether the current pipeline action is a "replace" or "merge"
|
|
266
|
+
* operation. Merge behaviors rely on this to apply correct semantics.
|
|
267
|
+
*/
|
|
268
|
+
operation: OperationType;
|
|
269
|
+
/**
|
|
270
|
+
* Optional behavior-specific configuration supplied for the current operation.
|
|
271
|
+
*/
|
|
272
|
+
options: unknown;
|
|
273
|
+
/**
|
|
274
|
+
* Emits when the FeatureCell is reset. Behaviors may use this to restore
|
|
275
|
+
* internal state or deferred work.
|
|
276
|
+
*/
|
|
277
|
+
reset$?: Observable<void>;
|
|
278
|
+
/**
|
|
279
|
+
* Identifies the resolve mode for the current operation.
|
|
280
|
+
* This is set by resolve behaviors during the resolve stage.
|
|
281
|
+
*/
|
|
282
|
+
resolveType?: ResolveType;
|
|
283
|
+
/**
|
|
284
|
+
* Immutable snapshot of the FeatureCell state at the start of the
|
|
285
|
+
* operation. Used by merge, reducer, filter, and operator behaviors to read
|
|
286
|
+
* the current state without mutating it.
|
|
287
|
+
*/
|
|
288
|
+
state: Readonly<StateSnapshotShape<T>>;
|
|
289
|
+
/**
|
|
290
|
+
* Emits when the state of the FeatureCell is updated.
|
|
291
|
+
*/
|
|
292
|
+
state$: Subject<StateEmitSnapshotShape<T> | undefined>;
|
|
293
|
+
/**
|
|
294
|
+
* The traceId for Devtools debugging and tracking
|
|
295
|
+
* Assigned by the orchestrator
|
|
296
|
+
*/
|
|
297
|
+
traceId: string;
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Defines configuration options that control which data is included in emitted insight events.
|
|
302
|
+
* This interface allows consumers to specify the level of state, payload, error, and queue detail captured during monitoring.
|
|
303
|
+
*/
|
|
304
|
+
interface InsightConfig {
|
|
305
|
+
/**
|
|
306
|
+
* Unique identifier for the insight definition.
|
|
307
|
+
* Commonly used to distinguish different monitoring consumers.
|
|
308
|
+
*/
|
|
309
|
+
id?: string;
|
|
310
|
+
/**
|
|
311
|
+
* Whether lifecycle events should include a snapshot of the
|
|
312
|
+
* FeatureCell’s current state value.
|
|
313
|
+
*/
|
|
314
|
+
wantsState?: boolean;
|
|
315
|
+
/**
|
|
316
|
+
* Whether emitted events should contain the operation payload such as
|
|
317
|
+
* reducer results, merge patches, or replacement values.
|
|
318
|
+
*/
|
|
319
|
+
wantsPayload?: boolean;
|
|
320
|
+
/**
|
|
321
|
+
* Whether error information should be included in emitted insight events.
|
|
322
|
+
*/
|
|
323
|
+
wantsErrors?: boolean;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
declare const DecisionOutcomeTypes: {
|
|
327
|
+
readonly Abort: "abort";
|
|
328
|
+
readonly Abstain: "abstain";
|
|
329
|
+
readonly Deny: "deny";
|
|
330
|
+
};
|
|
331
|
+
type DecisionOutcomeType = (typeof DecisionOutcomeTypes)[keyof typeof DecisionOutcomeTypes];
|
|
332
|
+
|
|
333
|
+
interface ControllerDecisionShape {
|
|
334
|
+
traceId: string;
|
|
335
|
+
outcome: DecisionOutcomeType;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
interface ControllerContext<T> {
|
|
339
|
+
traceId: string;
|
|
340
|
+
featureCellKey: string;
|
|
341
|
+
/** Immutable snapshot of the current cell state. */
|
|
342
|
+
snapshot: Readonly<StateSnapshotShape<T>>;
|
|
343
|
+
/** Raw incoming payload for replace/merge. */
|
|
344
|
+
incoming?: StateInputType<T>;
|
|
345
|
+
/** Replace or merge. */
|
|
346
|
+
operation: OperationType;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
type VaultMonitorContext<T> = BehaviorContext<T> | ControllerContext<T> | FeatureCellExtensionContext<T>;
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* Public interface for the VaultMonitor singleton.
|
|
353
|
+
*
|
|
354
|
+
* This interface defines the full DevTools-visible monitoring API
|
|
355
|
+
* without exposing implementation details.
|
|
356
|
+
*/
|
|
357
|
+
interface VaultMonitorContract {
|
|
358
|
+
activateGlobalInsights(definition: InsightConfig): void;
|
|
359
|
+
startAfterTap<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
360
|
+
endAfterTap<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
361
|
+
startBeforeTap<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
362
|
+
endBeforeTap<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
363
|
+
startComputeMerge<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
364
|
+
endComputeMerge<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
365
|
+
startClearPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
366
|
+
endClearPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
367
|
+
startCoreCallbackError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
368
|
+
endCoreCallbackError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
369
|
+
startCoreEmitState<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
370
|
+
endCoreEmitState<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
371
|
+
startCoreError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
372
|
+
endCoreError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
373
|
+
startCoreState<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
374
|
+
endCoreState<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
375
|
+
startDestroy<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
376
|
+
endDestroy<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
377
|
+
startDecrypt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
378
|
+
endDecrypt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
379
|
+
startEncrypt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
380
|
+
endEncrypt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
381
|
+
startFilter<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
382
|
+
endFilter<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
383
|
+
startGlobalError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
384
|
+
endGlobalError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
385
|
+
ingressSubscribed<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, source: string): void;
|
|
386
|
+
ingressCompleted<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, source: string): void;
|
|
387
|
+
startInterceptor<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
388
|
+
endInterceptor<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
389
|
+
startInitialized<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
390
|
+
endInitialized<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
391
|
+
startLoadPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
392
|
+
endLoadPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
393
|
+
startMerge<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
394
|
+
endMerge<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
395
|
+
startPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
396
|
+
endPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
397
|
+
startOperator<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
398
|
+
endOperator<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
399
|
+
startPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
400
|
+
endPersist<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
401
|
+
startReducer<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
402
|
+
endReducer<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
403
|
+
registerCell(cellKey: string, insight?: InsightConfig): void;
|
|
404
|
+
startReplace<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
405
|
+
endReplace<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
406
|
+
startReset<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
407
|
+
endReset<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
408
|
+
startResolve<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
409
|
+
endResolve<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
410
|
+
startSetInitialValue<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
411
|
+
endSetInitialValue<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
412
|
+
startStepwise<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
413
|
+
endStepwise<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload?: unknown): void;
|
|
414
|
+
notifyConductorDeny<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
415
|
+
conductorRevote<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
416
|
+
conductorAbort<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
417
|
+
conductorLicenseAttempt(cell: string, featureCellKey: string): void;
|
|
418
|
+
conductorLicenseApproved(cell: string, featureCellKey: string): void;
|
|
419
|
+
conductorLicenseDenied(cell: string, featureCellKey: string): void;
|
|
420
|
+
startControllerAttempt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
421
|
+
endControllerAttempt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload: unknown): void;
|
|
422
|
+
restartControllerAttempt<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload: string): void;
|
|
423
|
+
controllerFailure<T>(behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, error: unknown): void;
|
|
424
|
+
controllerFinalize<T>(behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
425
|
+
controllerSuccess<T>(behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
426
|
+
startControllerVote<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
427
|
+
endControllerVote<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload: ControllerDecisionShape): void;
|
|
428
|
+
conductorCrashed<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, error: unknown): void;
|
|
429
|
+
runtimeError<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, error: unknown): void;
|
|
430
|
+
warn<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, message: string): void;
|
|
431
|
+
startErrorTransform<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>): void;
|
|
432
|
+
endErrorTransform<T>(cell: string, behaviorKey: string, ctx: Readonly<VaultMonitorContext<T>>, payload: VaultErrorShape): void;
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
interface FeatureCellExtensionContext<T> {
|
|
436
|
+
destroyed$: Observable<void>;
|
|
437
|
+
featureCellKey: string;
|
|
438
|
+
mergeState(incoming: StateInputType<T>, options?: unknown): Promise<void>;
|
|
439
|
+
replaceState(input: StateInputType<T>, options?: unknown): Promise<void>;
|
|
440
|
+
reset$: Observable<void>;
|
|
441
|
+
state$: Observable<StateEmitSnapshotShape<T>>;
|
|
442
|
+
vaultMonitor: VaultMonitorContract;
|
|
443
|
+
options?: unknown;
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/**
|
|
447
|
+
* FeatureCell extensions registry.
|
|
448
|
+
*
|
|
449
|
+
* Every extended cell API method is added here via module augmentation.
|
|
450
|
+
*/
|
|
451
|
+
interface FeatureCellExtension<TEntity> {
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
interface FeatureCellFluentApi<TEntity> {
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
/**
|
|
458
|
+
* Runtime-safe registry of all behavior types.
|
|
459
|
+
*
|
|
460
|
+
* This object acts as an enum substitute without introducing JavaScript enum
|
|
461
|
+
* overhead.
|
|
462
|
+
* Values are string literals preserved at runtime and suitable for
|
|
463
|
+
* switch statements, comparisons, and pipeline classification.
|
|
464
|
+
* Each key maps 1:1 to its string literal value.
|
|
465
|
+
* The structure is fully tree-shakable and safely inferable by TypeScript.
|
|
466
|
+
*/
|
|
467
|
+
declare const BehaviorTypes: {
|
|
468
|
+
readonly CoreAfterTap: "coreAfterTap";
|
|
469
|
+
readonly CoreBeforeTap: "coreBeforeTap";
|
|
470
|
+
readonly ReplayGlobalError: "replayGlobalError";
|
|
471
|
+
readonly CoreError: "coreError";
|
|
472
|
+
readonly CoreErrorCallback: "coreErrorCallback";
|
|
473
|
+
readonly CoreState: "coreState";
|
|
474
|
+
readonly DevPipelineObserver: "devPipelineObserver";
|
|
475
|
+
readonly Encrypt: "encrypt";
|
|
476
|
+
readonly CoreEmitState: "coreEmitState";
|
|
477
|
+
readonly ErrorTransform: "errorTransform";
|
|
478
|
+
readonly Extension: "extension";
|
|
479
|
+
readonly Filter: "filter";
|
|
480
|
+
readonly FromObservable: "fromObservable";
|
|
481
|
+
readonly FromPromise: "fromPromise";
|
|
482
|
+
readonly FromStream: "fromStream";
|
|
483
|
+
readonly Interceptor: "interceptor";
|
|
484
|
+
readonly Merge: "merge";
|
|
485
|
+
readonly Operator: "operator";
|
|
486
|
+
readonly Persist: "persist";
|
|
487
|
+
readonly Reduce: "reduce";
|
|
488
|
+
readonly Resolve: "resolve";
|
|
489
|
+
readonly StepwiseFilter: "stepwiseFilter";
|
|
490
|
+
readonly StepwiseReducer: "stepwiseReducer";
|
|
491
|
+
readonly StepwiseResolve: "stepwiseResolve";
|
|
492
|
+
};
|
|
493
|
+
/**
|
|
494
|
+
* Union of all valid behavior type strings.
|
|
495
|
+
*
|
|
496
|
+
* This type is derived from `BehaviorTypes` using literal inference, ensuring
|
|
497
|
+
* strong typing while preserving full runtime compatibility.
|
|
498
|
+
* This type should not be manually extended—add new values to `BehaviorTypes`
|
|
499
|
+
* instead.
|
|
500
|
+
*
|
|
501
|
+
* --RelatedStart--
|
|
502
|
+
* BehaviorTypes
|
|
503
|
+
* --RelatedEnd--
|
|
504
|
+
*/
|
|
505
|
+
type BehaviorType = (typeof BehaviorTypes)[keyof typeof BehaviorTypes];
|
|
506
|
+
|
|
507
|
+
interface BehaviorClassContract<T = any> {
|
|
508
|
+
/**
|
|
509
|
+
* Creates a new behavior instance.
|
|
510
|
+
*
|
|
511
|
+
* @param behaviorKey - Unique key assigned by the behavior factory.
|
|
512
|
+
* @param behaviorCtx - The behaviorCtxfor dependency resolution.
|
|
513
|
+
*/
|
|
514
|
+
new (behaviorKey: string, behaviorCtx: BehaviorClassContext): BehaviorContract<T>;
|
|
515
|
+
readonly type: BehaviorType;
|
|
516
|
+
/**
|
|
517
|
+
* Unique identifier assigned to this behavior instance. Used by the
|
|
518
|
+
* orchestrator, diagnostics, and devtools for behavior correlation.
|
|
519
|
+
*/
|
|
520
|
+
readonly key: string;
|
|
521
|
+
/**
|
|
522
|
+
* If the actions of the behavior are critical in regards to error handling.
|
|
523
|
+
* True means the pipeline should VAULT_NOOP and stop the pipeline flow on any errors
|
|
524
|
+
* False means that pipeline should log any error and continue
|
|
525
|
+
*/
|
|
526
|
+
readonly critical: boolean;
|
|
527
|
+
installFluentApi?: <T>(cell: FeatureCellBaseShape<T>, behaviorConfigs: Map<string, unknown>) => void;
|
|
528
|
+
readonly wantsConfig?: boolean;
|
|
529
|
+
readonly configKey?: string;
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
interface InterceptorBehaviorClassContract<T> extends BehaviorClassContract<T> {
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
interface OperatorsBehaviorClassContract<T> extends BehaviorClassContract<T> {
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
type CoreEmitStateCallback<T, E = void> = (snapshot: StateSnapshotShape<T>) => E;
|
|
539
|
+
|
|
540
|
+
type TapCallback<T> = (current: T) => void;
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* A pure function used by the Filter behavior stage.
|
|
544
|
+
*
|
|
545
|
+
* A filter receives the current state value and must return either the same
|
|
546
|
+
* value or a transformed version of it. Implementations must be pure: they
|
|
547
|
+
* must not mutate the input value, trigger side effects, or access external
|
|
548
|
+
* mutable state. Filters execute before reducers and tap behaviors.
|
|
549
|
+
*
|
|
550
|
+
* @typeParam T - The state value type processed by this filter.
|
|
551
|
+
*/
|
|
552
|
+
type FilterFunction<T> = (current: T) => T;
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* A pure reducer function used by the Vault pipeline.
|
|
556
|
+
*
|
|
557
|
+
* A `ReducerFunction` receives the current pipeline value and must return
|
|
558
|
+
* a new pipeline value of the same type. Reducers should be pure and must
|
|
559
|
+
* not mutate the input. They are executed during the reducer stage of the
|
|
560
|
+
* pipeline and are responsible for producing deterministic, immutable
|
|
561
|
+
* state transitions.
|
|
562
|
+
*
|
|
563
|
+
* @typeParam T - The state slice or model type being reduced.
|
|
564
|
+
* @param current - The current state value before applying the reducer.
|
|
565
|
+
* @returns The next state value after transformation.
|
|
566
|
+
*/
|
|
567
|
+
type ReducerFunction<T> = (current: T) => T;
|
|
568
|
+
|
|
569
|
+
/**
|
|
570
|
+
* Defines the builder contract used to configure and initialize a FeatureCell.
|
|
571
|
+
* This interface exposes the fluent configuration surface for registering behaviors, callbacks, and operators prior to activation.
|
|
572
|
+
*
|
|
573
|
+
* --RelatedStart--
|
|
574
|
+
* FeatureCellExtension
|
|
575
|
+
* FeatureCellFluentApi
|
|
576
|
+
* CoreEmitStateCallback
|
|
577
|
+
* TapCallback
|
|
578
|
+
* VaultErrorCallback
|
|
579
|
+
* FilterFunction
|
|
580
|
+
* InterceptorBehaviorClassContract
|
|
581
|
+
* OperatorsBehaviorClassContract
|
|
582
|
+
* ReducerFunction
|
|
583
|
+
* --RelatedEnd--
|
|
584
|
+
*/
|
|
585
|
+
interface CellBuilderContract<T> extends FeatureCellExtension<T>, FeatureCellFluentApi<T> {
|
|
586
|
+
/**
|
|
587
|
+
* Registers functions executed during the "after tap" stage.
|
|
588
|
+
*
|
|
589
|
+
* @param afterTaps - Tap functions invoked after reducers.
|
|
590
|
+
* @returns The same builder instance for fluent chaining.
|
|
591
|
+
*/
|
|
592
|
+
afterTaps(afterTaps: TapCallback<T>[]): CellBuilderContract<T>;
|
|
593
|
+
/**
|
|
594
|
+
* Registers functions executed during the "before tap" stage.
|
|
595
|
+
*
|
|
596
|
+
* @param beforeTaps - Tap functions invoked before reducers.
|
|
597
|
+
* @returns The same builder instance for fluent chaining.
|
|
598
|
+
*/
|
|
599
|
+
beforeTaps(beforeTaps: TapCallback<T>[]): CellBuilderContract<T>;
|
|
600
|
+
/**
|
|
601
|
+
* Map of behavior configuration values keyed by behavior configuration identifiers.
|
|
602
|
+
*/
|
|
603
|
+
behaviorConfigs: Map<string, unknown>;
|
|
604
|
+
/**
|
|
605
|
+
* Registers emitState functions executed during the emitState stage.
|
|
606
|
+
*
|
|
607
|
+
* @param emitStates - EmitState callbacks invoked during state changes.
|
|
608
|
+
* @returns The builder instance for fluent chaining.
|
|
609
|
+
*/
|
|
610
|
+
emitStates(emitStates: CoreEmitStateCallback<T>[]): CellBuilderContract<T>;
|
|
611
|
+
/**
|
|
612
|
+
* Registers error functions to run during the error stage.
|
|
613
|
+
*CellBuilderContract
|
|
614
|
+
* @param errors - Error functions that may block or transform values.
|
|
615
|
+
* @returns The same builder instance for fluent chaining.
|
|
616
|
+
*/
|
|
617
|
+
errors(errors: VaultErrorCallback<T>[]): CellBuilderContract<T>;
|
|
618
|
+
/**
|
|
619
|
+
* Registers filter functions to run during the filter stage.
|
|
620
|
+
*
|
|
621
|
+
* @param filters - Filter functions that may block or transform values.
|
|
622
|
+
* @returns The same builder instance for fluent chaining.
|
|
623
|
+
*/
|
|
624
|
+
filters(filters: FilterFunction<T>[]): CellBuilderContract<T>;
|
|
625
|
+
hydrate(incoming: DeferredType<T>): CellBuilderContract<T>;
|
|
626
|
+
/**
|
|
627
|
+
* Finalizes the builder configuration and activates the FeatureCell.
|
|
628
|
+
*
|
|
629
|
+
* Implementations may perform synchronous or asynchronous setup.
|
|
630
|
+
*
|
|
631
|
+
* @returns The builder instance, or a Promise resolving when initialization completes.
|
|
632
|
+
*/
|
|
633
|
+
initialize(): void;
|
|
634
|
+
/**
|
|
635
|
+
* Registers interceptor behaviors that preprocess incoming state before resolve.
|
|
636
|
+
*
|
|
637
|
+
* @param interceptors - Interceptor behavior classes.
|
|
638
|
+
* @returns The same builder instance for fluent chaining.
|
|
639
|
+
*/
|
|
640
|
+
interceptors(interceptors: InterceptorBehaviorClassContract<T>[]): CellBuilderContract<T>;
|
|
641
|
+
/**
|
|
642
|
+
* Registers operator behaviors executed prior to filtering.
|
|
643
|
+
*
|
|
644
|
+
* @param operators - Operator behavior classes that may transform or block updates.
|
|
645
|
+
* @returns The same builder instance for fluent chaining.
|
|
646
|
+
*/
|
|
647
|
+
operators(operators: OperatorsBehaviorClassContract<T>[]): CellBuilderContract<T>;
|
|
648
|
+
/**
|
|
649
|
+
* Registers a sequence of reducer functions to run during the reducer stage.
|
|
650
|
+
*
|
|
651
|
+
* @param reducers - Ordered reducer functions applied to the working state.
|
|
652
|
+
* @returns The same builder instance for fluent chaining.
|
|
653
|
+
*/
|
|
654
|
+
reducers(reducers: ReducerFunction<T>[]): CellBuilderContract<T>;
|
|
655
|
+
}
|
|
656
|
+
|
|
657
|
+
/**
|
|
658
|
+
* Defines the public base contract for a FeatureCell instance.
|
|
659
|
+
* This interface exposes the full builder, lifecycle, and state update surface required to configure, initialize, and interact with a FeatureCell at runtime.
|
|
660
|
+
*/
|
|
661
|
+
interface FeatureCellBaseShape<T> extends FeatureCellExtension<T>, FeatureCellFluentApi<T> {
|
|
662
|
+
/**
|
|
663
|
+
* Registers tap functions executed during the "after tap" stage.
|
|
664
|
+
*
|
|
665
|
+
* @param afterTaps - Functions invoked after the reducer stage.
|
|
666
|
+
* @returns The builder instance for fluent chaining.
|
|
667
|
+
*/
|
|
668
|
+
afterTaps(afterTaps: TapCallback<T>[]): CellBuilderContract<T>;
|
|
669
|
+
/**
|
|
670
|
+
* Registers tap functions executed during the "before tap" stage.
|
|
671
|
+
*
|
|
672
|
+
* @param beforeTaps - Functions invoked before the reducer stage.
|
|
673
|
+
* @returns The builder instance for fluent chaining.
|
|
674
|
+
*/
|
|
675
|
+
beforeTaps(beforeTaps: TapCallback<T>[]): CellBuilderContract<T>;
|
|
676
|
+
/**
|
|
677
|
+
* Performs cleanup and teardown of the FeatureCell.
|
|
678
|
+
* Called automatically when the cell's hosting provider is destroyed.
|
|
679
|
+
*/
|
|
680
|
+
destroy(): void;
|
|
681
|
+
/**
|
|
682
|
+
* Observable that emits when the FeatureCell has been destroyed.
|
|
683
|
+
*/
|
|
684
|
+
destroyed$?: Observable<void>;
|
|
685
|
+
/**
|
|
686
|
+
* Registers emitState functions executed during the emitState stage.
|
|
687
|
+
*
|
|
688
|
+
* @param emitStates - EmitState callbacks invoked during state changes.
|
|
689
|
+
* @returns The builder instance for fluent chaining.
|
|
690
|
+
*/
|
|
691
|
+
emitStates(emitStates: CoreEmitStateCallback<T>[]): CellBuilderContract<T>;
|
|
692
|
+
/**
|
|
693
|
+
* Registers error functions to run during the error stage.
|
|
694
|
+
*
|
|
695
|
+
* @param errors - Error functions applied to the upstream snapshot.
|
|
696
|
+
* @returns The builder instance for fluent chaining.
|
|
697
|
+
*/
|
|
698
|
+
errors(errors: VaultErrorCallback<T>[]): CellBuilderContract<T>;
|
|
699
|
+
/**
|
|
700
|
+
* Registers filter functions to run during the filter stage.
|
|
701
|
+
*
|
|
702
|
+
* @param filters - Filter functions applied to the upstream snapshot.
|
|
703
|
+
* @returns The builder instance for fluent chaining.
|
|
704
|
+
*/
|
|
705
|
+
filters(filters: FilterFunction<T>[]): CellBuilderContract<T>;
|
|
706
|
+
hydrate(incoming: DeferredType<T>): CellBuilderContract<T>;
|
|
707
|
+
/**
|
|
708
|
+
* Finalizes builder configuration and activates the FeatureCell.
|
|
709
|
+
*
|
|
710
|
+
* @returns The builder instance, or a Promise resolving once initialization completes.
|
|
711
|
+
*/
|
|
712
|
+
initialize(): CellBuilderContract<T> | void;
|
|
713
|
+
/**
|
|
714
|
+
* Registers interceptor behaviors executed prior to resolve.
|
|
715
|
+
*
|
|
716
|
+
* @param interceptors - Interceptor behavior classes.
|
|
717
|
+
* @returns The builder instance for fluent chaining.
|
|
718
|
+
*/
|
|
719
|
+
interceptors(interceptors: InterceptorBehaviorClassContract<T>[]): CellBuilderContract<T>;
|
|
720
|
+
/**
|
|
721
|
+
* Unique identifier assigned to the FeatureCell.
|
|
722
|
+
*/
|
|
723
|
+
readonly key: string;
|
|
724
|
+
/**
|
|
725
|
+
* Performs a merge-style state update using the configured merge behavior.
|
|
726
|
+
*
|
|
727
|
+
* @param incoming Structured state input to be merged.
|
|
728
|
+
* @param options Optional merge behavior configuration.
|
|
729
|
+
*/
|
|
730
|
+
mergeState(incoming: StateInputType<T>, options?: unknown): void;
|
|
731
|
+
/**
|
|
732
|
+
* Registers operator behaviors executed before filters.
|
|
733
|
+
*
|
|
734
|
+
* @param operators - Operator behavior classes.
|
|
735
|
+
* @returns The builder instance for fluent chaining.
|
|
736
|
+
*/
|
|
737
|
+
operators(operators: OperatorsBehaviorClassContract<T>[]): CellBuilderContract<T>;
|
|
738
|
+
/**
|
|
739
|
+
* Registers reducer functions executed during the reducer stage.
|
|
740
|
+
*
|
|
741
|
+
* @param reducers - Reducer functions that transform the working state.
|
|
742
|
+
* @returns The builder instance for fluent chaining.
|
|
743
|
+
*/
|
|
744
|
+
reducers(reducers: ReducerFunction<T>[]): CellBuilderContract<T>;
|
|
745
|
+
/**
|
|
746
|
+
* Performs a replace-style state update that fully replaces the current state.
|
|
747
|
+
*
|
|
748
|
+
* @param incoming Structured state input to replace the current state.
|
|
749
|
+
* @param options Optional merge behavior configuration.
|
|
750
|
+
*/
|
|
751
|
+
replaceState(incoming: StateInputType<T>, options?: unknown): void;
|
|
752
|
+
/**
|
|
753
|
+
* Resets the FeatureCell to its initial state.
|
|
754
|
+
*/
|
|
755
|
+
reset(): void;
|
|
756
|
+
/**
|
|
757
|
+
* Observable that emits when the FeatureCell has been reset.
|
|
758
|
+
*/
|
|
759
|
+
reset$?: Observable<void>;
|
|
760
|
+
/**
|
|
761
|
+
* Observable that emits when the FeatureCell has been reset.
|
|
762
|
+
*/
|
|
763
|
+
state$: Observable<StateEmitSnapshotShape<T>>;
|
|
764
|
+
/**
|
|
765
|
+
* Dev-mode testing hook.
|
|
766
|
+
* Only defined when DevMode.active === true.
|
|
767
|
+
* Non-enumerable and not part of runtime API.
|
|
768
|
+
*/
|
|
769
|
+
vaultSettled?: () => Promise<void>;
|
|
770
|
+
}
|
|
771
|
+
|
|
772
|
+
type BehaviorExtFunction = (...args: any[]) => unknown;
|
|
773
|
+
/**
|
|
774
|
+
* A map of extension function names to their implementation functions.
|
|
775
|
+
* Behaviors may return these objects to expose additional APIs on the
|
|
776
|
+
* FeatureCell instance. Keys correspond to method names added to the
|
|
777
|
+
* cell’s public API surface.
|
|
778
|
+
*/
|
|
779
|
+
type BehaviorExtension = Partial<Record<string, BehaviorExtFunction>>;
|
|
780
|
+
/**
|
|
781
|
+
* Base interface implemented by all behavior types in the SDuX/ Vault
|
|
782
|
+
* pipeline. Behaviors participate in specific pipeline stages based on
|
|
783
|
+
* their declared BehaviorType, and may optionally expose additional
|
|
784
|
+
* FeatureCell APIs through the `extendCellAPI()` hook.
|
|
785
|
+
*
|
|
786
|
+
* @typeParam T - The FeatureCell state value type handled by this behavior.
|
|
787
|
+
* @typeParam E - The shape of the extension API returned by this behavior.
|
|
788
|
+
*/
|
|
789
|
+
interface BehaviorContract<T = unknown, E extends BehaviorExtension = BehaviorExtension> {
|
|
790
|
+
/**
|
|
791
|
+
* Declares the pipeline classification for this behavior. The orchestrator
|
|
792
|
+
* uses this to determine the execution order in the upstream and persist
|
|
793
|
+
* stages.
|
|
794
|
+
*/
|
|
795
|
+
readonly type: BehaviorType;
|
|
796
|
+
/**
|
|
797
|
+
* Unique identifier assigned to this behavior instance. Used by the
|
|
798
|
+
* orchestrator, diagnostics, and devtools for behavior correlation.
|
|
799
|
+
*/
|
|
800
|
+
readonly key: string;
|
|
801
|
+
/**
|
|
802
|
+
* If the actions of the behavior are critical in regards to error handling.
|
|
803
|
+
* True means the pipeline should VAULT_NOOP and stop the pipeline flow on any errors
|
|
804
|
+
* False means that pipeline should log any error and continue
|
|
805
|
+
*/
|
|
806
|
+
readonly critical: boolean;
|
|
807
|
+
/**
|
|
808
|
+
* Optional list of extension function names that this behavior is permitted
|
|
809
|
+
* to override when multiple behaviors contribute conflicting API keys.
|
|
810
|
+
* Behaviors without explicit override permission may not replace an
|
|
811
|
+
* existing API entry.
|
|
812
|
+
*/
|
|
813
|
+
allowOverride?: string[];
|
|
814
|
+
extendCellAPI?(ctx: FeatureCellExtensionContext<T>): E | void;
|
|
815
|
+
destroy(ctx?: BehaviorContext<T>): void;
|
|
816
|
+
reset(ctx?: BehaviorContext<T>): void;
|
|
817
|
+
installFluentApi?: <T>(cell: FeatureCellBaseShape<T>, behaviorConfigs: Map<string, unknown>) => void;
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
interface ErrorCallbackBehaviorContract<T> extends BehaviorContract<T> {
|
|
821
|
+
type: 'coreErrorCallback';
|
|
822
|
+
callbackError(current: VaultErrorShape, state: StateSnapshotShape<T>, oldschoolCallback: VaultErrorCallback<T>): Promise<void>;
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
declare abstract class AbstractErrorCallbackBehavior<T> implements ErrorCallbackBehaviorContract<T> {
|
|
826
|
+
readonly behaviorCtx: BehaviorClassContext;
|
|
827
|
+
/** Indicates that this error behavior is critical and always executed. */
|
|
828
|
+
readonly critical: boolean;
|
|
829
|
+
/** Unique identifier for this behavior instance. */
|
|
830
|
+
readonly key: string;
|
|
831
|
+
/** Behavior type for orchestrator registration. */
|
|
832
|
+
readonly type: "coreErrorCallback";
|
|
833
|
+
/**
|
|
834
|
+
* Creates a new abstract error behavior instance.
|
|
835
|
+
*
|
|
836
|
+
* @param key - Unique behavior identifier supplied by the behavior factory.
|
|
837
|
+
* @param behaviorCtx - Behavior class context providing injector access and extensibility hooks.
|
|
838
|
+
*/
|
|
839
|
+
constructor(key: string, behaviorCtx: BehaviorClassContext);
|
|
840
|
+
abstract callbackError(current: VaultErrorShape, state: StateSnapshotShape<T>, oldschoolCallback: VaultErrorCallback<T>): Promise<void>;
|
|
841
|
+
/**
|
|
842
|
+
* Lifecycle hook invoked when the behavior instance is destroyed.
|
|
843
|
+
*
|
|
844
|
+
* Error behaviors do not allocate runtime resources and therefore require
|
|
845
|
+
* no cleanup. A diagnostic entry is logged for lifecycle visibility.
|
|
846
|
+
*/
|
|
847
|
+
destroy(): void;
|
|
848
|
+
/**
|
|
849
|
+
* Lifecycle hook invoked when the behavior instance is reset.
|
|
850
|
+
*
|
|
851
|
+
* Error behaviors hold no internal state, making this a no-operation.
|
|
852
|
+
* The hook ensures lifecycle uniformity across all behaviors.
|
|
853
|
+
*/
|
|
854
|
+
reset(): void;
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
declare const VAULT_NOOP: unique symbol;
|
|
858
|
+
|
|
859
|
+
interface ErrorTransformBehaviorContract<T> extends BehaviorContract<T> {
|
|
860
|
+
type: 'errorTransform';
|
|
861
|
+
transformError(error: unknown, current: VaultErrorShape, previousStateSnapshot: StateSnapshotShape<T>): Promise<unknown | typeof VAULT_NOOP>;
|
|
862
|
+
}
|
|
863
|
+
|
|
864
|
+
/**
|
|
865
|
+
* Abstract base behavior for transforming errors during pipeline execution.
|
|
866
|
+
* This class defines the contract and lifecycle hooks required for error transformation behaviors.
|
|
867
|
+
*
|
|
868
|
+
* --RelatedStart--
|
|
869
|
+
* ErrorTransformBehaviorContract
|
|
870
|
+
* BehaviorClassContext
|
|
871
|
+
* StateSnapshotShape
|
|
872
|
+
* VaultErrorShape
|
|
873
|
+
* --RelatedEnd--
|
|
874
|
+
*/
|
|
875
|
+
declare abstract class AbstractErrorTransformBehavior<T> implements ErrorTransformBehaviorContract<T> {
|
|
876
|
+
readonly behaviorCtx: BehaviorClassContext;
|
|
877
|
+
/**
|
|
878
|
+
* Indicates that this error transform behavior is critical and always executed.
|
|
879
|
+
*/
|
|
880
|
+
readonly critical: boolean;
|
|
881
|
+
/**
|
|
882
|
+
* Unique identifier for this behavior instance.
|
|
883
|
+
*/
|
|
884
|
+
readonly key: string;
|
|
885
|
+
/**
|
|
886
|
+
* Behavior type identifier used for orchestrator registration.
|
|
887
|
+
*/
|
|
888
|
+
readonly type: "errorTransform";
|
|
889
|
+
/**
|
|
890
|
+
* Creates a new abstract error transform behavior instance.
|
|
891
|
+
*
|
|
892
|
+
* @param key Unique behavior identifier supplied by the factory.
|
|
893
|
+
* @param behaviorCtx Behavior class context providing configuration and hooks.
|
|
894
|
+
*/
|
|
895
|
+
constructor(key: string, behaviorCtx: BehaviorClassContext);
|
|
896
|
+
/**
|
|
897
|
+
* Transforms an error produced during pipeline execution.
|
|
898
|
+
*
|
|
899
|
+
* @param error Incoming error value to be transformed.
|
|
900
|
+
* @param current Current normalized Vault error value.
|
|
901
|
+
* @param previousStateSnapshot Snapshot of state prior to the error.
|
|
902
|
+
* @returns Transformed error, original error, or VAULT_NOOP to suppress emission.
|
|
903
|
+
*/
|
|
904
|
+
abstract transformError(error: unknown, current: VaultErrorShape, previousStateSnapshot: StateSnapshotShape<T>): Promise<unknown | typeof VAULT_NOOP>;
|
|
905
|
+
/**
|
|
906
|
+
* Lifecycle hook invoked when the behavior instance is destroyed.
|
|
907
|
+
*/
|
|
908
|
+
destroy(): void;
|
|
909
|
+
/**
|
|
910
|
+
* Lifecycle hook invoked when the behavior instance is reset.
|
|
911
|
+
*/
|
|
912
|
+
reset(): void;
|
|
913
|
+
}
|
|
914
|
+
|
|
915
|
+
interface ControllerClassContext {
|
|
916
|
+
featureCellKey: string;
|
|
917
|
+
requestRevote: (traceId: string) => void;
|
|
918
|
+
requestAbort: (traceId: string) => void;
|
|
919
|
+
licenseDenied?: (traceId: string) => void;
|
|
920
|
+
licenseApproved?: (traceId: string) => void;
|
|
921
|
+
readonly controllerConfig?: unknown;
|
|
922
|
+
readonly licensePayload?: unknown;
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
declare const ControllerMessageTypes: {
|
|
926
|
+
readonly Attempt: "attempt";
|
|
927
|
+
readonly Failure: "failure";
|
|
928
|
+
readonly Finalize: "Finalize Pipeline";
|
|
929
|
+
readonly Success: "success";
|
|
930
|
+
readonly Vote: "vote";
|
|
931
|
+
};
|
|
932
|
+
type ControllerMessageType = (typeof ControllerMessageTypes)[keyof typeof ControllerMessageTypes];
|
|
933
|
+
|
|
934
|
+
interface ControllerMessageBaseShape {
|
|
935
|
+
type: ControllerMessageType;
|
|
936
|
+
traceId: string;
|
|
937
|
+
}
|
|
938
|
+
|
|
939
|
+
interface ControllerAttemptMessageShape<T> extends ControllerMessageBaseShape {
|
|
940
|
+
type: typeof ControllerMessageTypes.Attempt;
|
|
941
|
+
ctx: ControllerContext<T>;
|
|
942
|
+
}
|
|
943
|
+
|
|
944
|
+
interface ControllerFailMessageShape<T> extends ControllerMessageBaseShape {
|
|
945
|
+
type: typeof ControllerMessageTypes.Failure;
|
|
946
|
+
ctx: ControllerContext<T>;
|
|
947
|
+
error: VaultErrorShape | unknown;
|
|
948
|
+
}
|
|
949
|
+
|
|
950
|
+
interface ControllerFinalizeMessageShape extends ControllerMessageBaseShape {
|
|
951
|
+
type: typeof ControllerMessageTypes.Finalize;
|
|
952
|
+
}
|
|
953
|
+
|
|
954
|
+
interface ControllerSuccessMessageShape<T> extends ControllerMessageBaseShape {
|
|
955
|
+
type: typeof ControllerMessageTypes.Success;
|
|
956
|
+
ctx: ControllerContext<T>;
|
|
957
|
+
}
|
|
958
|
+
|
|
959
|
+
type ControllerMessageShape<T> = ControllerAttemptMessageShape<T> | ControllerSuccessMessageShape<T> | ControllerFailMessageShape<T> | ControllerFinalizeMessageShape;
|
|
960
|
+
|
|
961
|
+
declare const ControllerVotes: {
|
|
962
|
+
readonly Abstain: "abstain";
|
|
963
|
+
readonly Abort: "abort";
|
|
964
|
+
readonly Deny: "deny";
|
|
965
|
+
};
|
|
966
|
+
type ControllerVote = (typeof ControllerVotes)[keyof typeof ControllerVotes];
|
|
967
|
+
|
|
968
|
+
declare const ControllerTypes: {
|
|
969
|
+
readonly CoreAbstain: "coreAbstain";
|
|
970
|
+
readonly Error: "error";
|
|
971
|
+
readonly License: "license";
|
|
972
|
+
readonly Policy: "policy";
|
|
973
|
+
readonly ReplayGlobalError: "replayGlobalError";
|
|
974
|
+
readonly Stepwise: "stepwise";
|
|
975
|
+
};
|
|
976
|
+
type ControllerType = (typeof ControllerTypes)[keyof typeof ControllerTypes];
|
|
977
|
+
|
|
978
|
+
interface ControllerContract<T = unknown> {
|
|
979
|
+
readonly type: ControllerType;
|
|
980
|
+
readonly key: string;
|
|
981
|
+
readonly critical: boolean;
|
|
982
|
+
handleMessage(msg: ControllerMessageShape<T>): Observable<ControllerVote | void>;
|
|
983
|
+
destroy(): void;
|
|
984
|
+
reset(): void;
|
|
985
|
+
installFluentApi?: <T>(cell: FeatureCellBaseShape<T>, behaviorConfigs: Map<string, unknown>) => void;
|
|
986
|
+
}
|
|
987
|
+
|
|
988
|
+
declare abstract class AbstractActiveController<T> implements ControllerContract<T> {
|
|
989
|
+
#private;
|
|
990
|
+
protected readonly ctx: ControllerClassContext;
|
|
991
|
+
readonly key: string;
|
|
992
|
+
abstract readonly type: ControllerType;
|
|
993
|
+
readonly critical = false;
|
|
994
|
+
protected hasError: boolean;
|
|
995
|
+
protected traceId: string | null;
|
|
996
|
+
constructor(key: string, ctx: ControllerClassContext);
|
|
997
|
+
/** Child classes override to react to external error toggles */
|
|
998
|
+
protected onExternalTrigger(_newErrorState: boolean): void;
|
|
999
|
+
/** All controllers must implement this */
|
|
1000
|
+
abstract handleMessage(msg: ControllerMessageShape<T>): Observable<ControllerVote | void>;
|
|
1001
|
+
destroy(): void;
|
|
1002
|
+
reset(): void;
|
|
1003
|
+
}
|
|
1004
|
+
|
|
1005
|
+
/**
|
|
1006
|
+
* Configuration options for merge operations executed by a MergeBehavior.
|
|
1007
|
+
*
|
|
1008
|
+
* `MergeConfig` allows callers to influence how undefined values are treated
|
|
1009
|
+
* during state merging. These options are consumed by the active merge strategy
|
|
1010
|
+
* (e.g., array replace, append, shallow object merge, deep merge).
|
|
1011
|
+
*/
|
|
1012
|
+
interface MergeConfig {
|
|
1013
|
+
/**
|
|
1014
|
+
* When enabled, properties with `undefined` values in the incoming snapshot
|
|
1015
|
+
* will clear corresponding properties on the current state. When disabled,
|
|
1016
|
+
* incoming `undefined` values leave existing state properties unchanged.
|
|
1017
|
+
*/
|
|
1018
|
+
clearUndefined?: boolean;
|
|
1019
|
+
}
|
|
1020
|
+
|
|
1021
|
+
/**
|
|
1022
|
+
* Configuration options for deep object merge behaviors.
|
|
1023
|
+
*
|
|
1024
|
+
* `ObjectDeepMergeConfig` influences how nested object structures are merged
|
|
1025
|
+
* during a deep-merge operation. These settings are applied recursively by the
|
|
1026
|
+
* merge behavior and determine how undefined and null-valued fields are handled.
|
|
1027
|
+
*/
|
|
1028
|
+
interface ObjectDeepMergeConfig {
|
|
1029
|
+
/**
|
|
1030
|
+
* When enabled, incoming `undefined` values will clear matching properties
|
|
1031
|
+
* on the current state during the merge. When disabled, `undefined` values
|
|
1032
|
+
* leave existing fields unchanged.
|
|
1033
|
+
*/
|
|
1034
|
+
clearUndefined?: boolean;
|
|
1035
|
+
/**
|
|
1036
|
+
* When enabled, properties whose incoming value is `null` are removed from the
|
|
1037
|
+
* merged output. When disabled, incoming `null` values are preserved during the
|
|
1038
|
+
* merge operation.
|
|
1039
|
+
*/
|
|
1040
|
+
stripNulls?: boolean;
|
|
1041
|
+
}
|
|
1042
|
+
|
|
1043
|
+
interface VaultLicensingShape {
|
|
1044
|
+
licenseId: string;
|
|
1045
|
+
payload: unknown;
|
|
1046
|
+
}
|
|
1047
|
+
|
|
1048
|
+
/**
|
|
1049
|
+
* Defines the allowable verbosity levels for Vault logging.
|
|
1050
|
+
*
|
|
1051
|
+
* A `LogLevel` controls the amount of diagnostic output emitted by the
|
|
1052
|
+
* vault’s internal debug, warning, or error channels. Higher levels
|
|
1053
|
+
* produce more detailed logs, while lower levels suppress output.
|
|
1054
|
+
*
|
|
1055
|
+
* - `'off'` — no logs are emitted
|
|
1056
|
+
* - `'error'` — only errors are logged
|
|
1057
|
+
* - `'warn'` — warnings and errors are logged
|
|
1058
|
+
* - `'log'` — standard log events, warnings, and errors are logged
|
|
1059
|
+
* - `'debug'` — all debug-level information is emitted
|
|
1060
|
+
*/
|
|
1061
|
+
declare const LogLevelTypes: {
|
|
1062
|
+
readonly Off: "off";
|
|
1063
|
+
readonly Error: "error";
|
|
1064
|
+
readonly Warn: "warn";
|
|
1065
|
+
readonly Log: "log";
|
|
1066
|
+
readonly Debug: "debug";
|
|
1067
|
+
};
|
|
1068
|
+
type LogLevelType = (typeof LogLevelTypes)[keyof typeof LogLevelTypes];
|
|
1069
|
+
|
|
1070
|
+
interface VaultConfig {
|
|
1071
|
+
/**
|
|
1072
|
+
* Enables development-mode diagnostics and additional internal checks.
|
|
1073
|
+
* When `true`, Vault emits more verbose warnings and validation errors.
|
|
1074
|
+
*/
|
|
1075
|
+
devMode?: boolean;
|
|
1076
|
+
/**
|
|
1077
|
+
* Controls the verbosity of internal logging.
|
|
1078
|
+
* Common levels: `'debug' | 'info' | 'warn' | 'error' | 'off'`.
|
|
1079
|
+
*/
|
|
1080
|
+
logLevel?: LogLevelType;
|
|
1081
|
+
/**
|
|
1082
|
+
* Optional array of pre-registered license payloads.
|
|
1083
|
+
*
|
|
1084
|
+
* Vault stores these payloads in memory at startup and makes them
|
|
1085
|
+
* retrievable via `getLicensePayload(licenseId)`. Vault does not
|
|
1086
|
+
* validate or interpret the payload — vendors are responsible for
|
|
1087
|
+
* validation logic.
|
|
1088
|
+
*/
|
|
1089
|
+
licenses?: VaultLicensingShape[];
|
|
1090
|
+
/**
|
|
1091
|
+
* Maximum time (in milliseconds) Vault will wait for a required
|
|
1092
|
+
* license to be validated before marking it as timed out.
|
|
1093
|
+
*
|
|
1094
|
+
* If validation does not occur within this window, the FeatureCell
|
|
1095
|
+
* is denied. Defaults to 15,000 ms. Set to `0` to disable timeout.
|
|
1096
|
+
*/
|
|
1097
|
+
licenseTimeoutMs?: number;
|
|
1098
|
+
}
|
|
1099
|
+
|
|
1100
|
+
declare const BEHAVIOR_META: unique symbol;
|
|
1101
|
+
|
|
1102
|
+
declare const CONTROLLER_META: unique symbol;
|
|
1103
|
+
|
|
1104
|
+
/**
|
|
1105
|
+
* String token used to uniquely identify the DevTools Aggregate FeatureCell.
|
|
1106
|
+
*
|
|
1107
|
+
* This key is referenced by the DevTools service, monitor utilities,
|
|
1108
|
+
* and the router configuration to ensure all DevTools-related state
|
|
1109
|
+
* is consistently mapped to the same FeatureCell instance.
|
|
1110
|
+
*
|
|
1111
|
+
* The value is stable across versions to maintain compatibility with
|
|
1112
|
+
* external tools such as the Chrome DevTools extension.
|
|
1113
|
+
*/
|
|
1114
|
+
declare const DEVTOOLS_AGGREGATE_KEY_CONSTANT = "vault::devtools::aggregate:feature::cell";
|
|
1115
|
+
|
|
1116
|
+
/**
|
|
1117
|
+
* String token used to uniquely identify the DevTools Logging FeatureCell.
|
|
1118
|
+
*
|
|
1119
|
+
* This key is referenced by the DevTools service, monitor utilities,
|
|
1120
|
+
* and the router configuration to ensure all DevTools-related state
|
|
1121
|
+
* is consistently mapped to the same FeatureCell instance.
|
|
1122
|
+
*
|
|
1123
|
+
* The value is stable across versions to maintain compatibility with
|
|
1124
|
+
* external tools such as the Chrome DevTools extension.
|
|
1125
|
+
*/
|
|
1126
|
+
declare const DEVTOOLS_LOGGING_KEY_CONSTANT = "vault::devtools::logging::feature::cell";
|
|
1127
|
+
|
|
1128
|
+
declare const VAULT_CLEAR_STATE: unique symbol;
|
|
1129
|
+
|
|
1130
|
+
declare const VAULT_CONTINUE: unique symbol;
|
|
1131
|
+
|
|
1132
|
+
declare const VAULT_STOP: unique symbol;
|
|
1133
|
+
|
|
1134
|
+
interface BehaviorMetaShape {
|
|
1135
|
+
/**
|
|
1136
|
+
* The pipeline stage in which this behavior participates.
|
|
1137
|
+
* Determines when the orchestrator invokes the behavior.
|
|
1138
|
+
*/
|
|
1139
|
+
type: BehaviorType;
|
|
1140
|
+
/**
|
|
1141
|
+
* Unique identifier for this behavior. Used for diagnostics,
|
|
1142
|
+
* devtools visualization, and orchestrator classification.
|
|
1143
|
+
*/
|
|
1144
|
+
key: string;
|
|
1145
|
+
/**
|
|
1146
|
+
* Indicates whether this behavior is critical. Critical behaviors
|
|
1147
|
+
* are mandatory and must always run when present in the pipeline.
|
|
1148
|
+
*/
|
|
1149
|
+
critical: boolean;
|
|
1150
|
+
/**
|
|
1151
|
+
* Optional resolve strategy associated with this behavior.
|
|
1152
|
+
* Only set for resolution behaviors that determine how state
|
|
1153
|
+
* is initially derived (e.g., value, http, observable).
|
|
1154
|
+
*/
|
|
1155
|
+
resolveType?: ResolveType;
|
|
1156
|
+
wantsConfig?: boolean;
|
|
1157
|
+
configKey?: string;
|
|
1158
|
+
needsLicense?: boolean;
|
|
1159
|
+
licenseId?: string;
|
|
1160
|
+
}
|
|
1161
|
+
|
|
1162
|
+
/**
|
|
1163
|
+
* Decorator that registers a class as an Vault behavior.
|
|
1164
|
+
*
|
|
1165
|
+
* The `VaultBehavior` decorator attaches the provided `BehaviorMeta`
|
|
1166
|
+
* definition to the target constructor, making the behavior discoverable by
|
|
1167
|
+
* the orchestrator during pipeline initialization. Metadata fields such as
|
|
1168
|
+
* `type`, `key`, and `critical` are also mirrored onto static properties of
|
|
1169
|
+
* the decorated class to support lightweight runtime introspection.
|
|
1170
|
+
*
|
|
1171
|
+
* This decorator does not modify method logic or structure; it only assigns
|
|
1172
|
+
* metadata required for orchestrator classification and behavior lifecycle
|
|
1173
|
+
* management.
|
|
1174
|
+
*
|
|
1175
|
+
* @param meta - Metadata describing the behavior’s category, unique key, and
|
|
1176
|
+
* criticality within the pipeline.
|
|
1177
|
+
* @returns A class decorator that applies behavior metadata to the target.
|
|
1178
|
+
*/
|
|
1179
|
+
declare function VaultBehavior(meta: BehaviorMetaShape): (target: any) => void;
|
|
1180
|
+
|
|
1181
|
+
interface ControllerMetaShape {
|
|
1182
|
+
type: ControllerType;
|
|
1183
|
+
key: string;
|
|
1184
|
+
critical?: boolean;
|
|
1185
|
+
wantsConfig?: boolean;
|
|
1186
|
+
configKey?: string;
|
|
1187
|
+
needsLicense?: boolean;
|
|
1188
|
+
licenseId?: string;
|
|
1189
|
+
}
|
|
1190
|
+
|
|
1191
|
+
declare function VaultController(meta: ControllerMetaShape): (target: any) => void;
|
|
1192
|
+
|
|
1193
|
+
declare const VaultErrorUsageKindTypes: {
|
|
1194
|
+
readonly Encryption: "VaultErrorEncryption";
|
|
1195
|
+
readonly License: "VaultErrorLicense";
|
|
1196
|
+
readonly Promise: "VaultErrorUsagePromise";
|
|
1197
|
+
readonly PromiseFactoryRequired: "VaultErrorUsagePromiseFactoryRequired";
|
|
1198
|
+
readonly Usage: "VaultErrorUsage";
|
|
1199
|
+
};
|
|
1200
|
+
type VaultErrorUsageKindType = (typeof VaultErrorUsageKindTypes)[keyof typeof VaultErrorUsageKindTypes];
|
|
1201
|
+
|
|
1202
|
+
declare const VaultErrorKindTypes: {
|
|
1203
|
+
readonly Usage: "VaultErrorUsage";
|
|
1204
|
+
readonly VaultError: "VaultError";
|
|
1205
|
+
};
|
|
1206
|
+
type VaultErrorKindType = (typeof VaultErrorKindTypes)[keyof typeof VaultErrorKindTypes] | (typeof VaultErrorUsageKindTypes)[keyof typeof VaultErrorUsageKindTypes];
|
|
1207
|
+
|
|
1208
|
+
declare const VaultErrorNameTypes: {
|
|
1209
|
+
readonly EncryptionIntegrity: "VaultErrorEncryptionIntegrity";
|
|
1210
|
+
readonly License: "VaultErrorLicense";
|
|
1211
|
+
readonly Usage: "VaultErrorUsage";
|
|
1212
|
+
readonly VaultError: "VaultError";
|
|
1213
|
+
};
|
|
1214
|
+
type VaultErrorNameType = (typeof VaultErrorNameTypes)[keyof typeof VaultErrorNameTypes];
|
|
1215
|
+
|
|
1216
|
+
declare class VaultError extends Error {
|
|
1217
|
+
readonly kind: VaultErrorKindType;
|
|
1218
|
+
constructor(message: string, name?: VaultErrorNameType, kind?: VaultErrorKindType);
|
|
1219
|
+
}
|
|
1220
|
+
|
|
1221
|
+
/**
|
|
1222
|
+
* Thrown when encrypted payload integrity verification fails.
|
|
1223
|
+
*
|
|
1224
|
+
* This occurs when AES-GCM authentication fails during decryption.
|
|
1225
|
+
* Causes may include:
|
|
1226
|
+
*
|
|
1227
|
+
* - Tampered ciphertext
|
|
1228
|
+
* - Modified IV
|
|
1229
|
+
* - Incorrect encryption key
|
|
1230
|
+
* - Corrupted storage payload
|
|
1231
|
+
*
|
|
1232
|
+
* AES-GCM provides authenticated encryption, so any modification to the
|
|
1233
|
+
* encrypted envelope will cause the WebCrypto decrypt operation to throw.
|
|
1234
|
+
*/
|
|
1235
|
+
declare class VaultEncryptionIntegrityError extends VaultError {
|
|
1236
|
+
constructor();
|
|
1237
|
+
}
|
|
1238
|
+
|
|
1239
|
+
declare class VaultLicenseError extends VaultError {
|
|
1240
|
+
constructor(message: string, kind?: VaultErrorUsageKindType);
|
|
1241
|
+
}
|
|
1242
|
+
|
|
1243
|
+
declare class VaultUsageError extends VaultError {
|
|
1244
|
+
constructor(message: string, kind?: VaultErrorUsageKindType);
|
|
1245
|
+
}
|
|
1246
|
+
|
|
1247
|
+
declare class VaultUsagePromiseError extends VaultUsageError {
|
|
1248
|
+
constructor();
|
|
1249
|
+
}
|
|
1250
|
+
|
|
1251
|
+
declare class VaultUsagePromiseFactoryRequiredError extends VaultUsageError {
|
|
1252
|
+
constructor();
|
|
1253
|
+
}
|
|
1254
|
+
|
|
1255
|
+
/**
|
|
1256
|
+
* Represents the possible result of a core emit operation.
|
|
1257
|
+
* This type indicates either an intentional no-op signal or the absence of an emitted state.
|
|
1258
|
+
*
|
|
1259
|
+
* --RelatedStart--
|
|
1260
|
+
* VAULT_NOOP
|
|
1261
|
+
* --RelatedEnd--
|
|
1262
|
+
*/
|
|
1263
|
+
type CoreEmitStateResult = typeof VAULT_NOOP | undefined;
|
|
1264
|
+
|
|
1265
|
+
/**
|
|
1266
|
+
* Contract for behaviors that emit finalized state snapshots.
|
|
1267
|
+
*/
|
|
1268
|
+
interface CoreEmitStateBehaviorContract<T> extends BehaviorContract<T> {
|
|
1269
|
+
/**
|
|
1270
|
+
* Emits a state snapshot through the configured emit callback.
|
|
1271
|
+
*
|
|
1272
|
+
* @param snapshot - The finalized state snapshot.
|
|
1273
|
+
* @param callback - The callback invoked with the snapshot.
|
|
1274
|
+
* @returns The emit result indicating pipeline continuation behavior.
|
|
1275
|
+
*/
|
|
1276
|
+
emitState(snapshot: StateSnapshotShape<T>, callback: CoreEmitStateCallback<T>): CoreEmitStateResult;
|
|
1277
|
+
}
|
|
1278
|
+
|
|
1279
|
+
/**
|
|
1280
|
+
* Behavior contract for observing pipeline execution events in development mode.
|
|
1281
|
+
*
|
|
1282
|
+
* This interface defines the lifecycle hooks and notification methods used by
|
|
1283
|
+
* a dev-only pipeline observer behavior to track execution boundaries and
|
|
1284
|
+
* propagate success or error signals associated with a FeatureCell run.
|
|
1285
|
+
*/
|
|
1286
|
+
interface DevPipelineObserverBehaviorContract extends BehaviorContract {
|
|
1287
|
+
/**
|
|
1288
|
+
* Signals the start of a pipeline execution cycle.
|
|
1289
|
+
*/
|
|
1290
|
+
beginRun(): void;
|
|
1291
|
+
/**
|
|
1292
|
+
* Emits a successful pipeline completion event for a FeatureCell.
|
|
1293
|
+
*
|
|
1294
|
+
* @param cellKey - The unique key of the FeatureCell that completed successfully.
|
|
1295
|
+
*/
|
|
1296
|
+
emitSuccess(cellKey: string): void;
|
|
1297
|
+
/**
|
|
1298
|
+
* Emits a pipeline error event for a FeatureCell.
|
|
1299
|
+
*
|
|
1300
|
+
* @param cellKey - The unique key of the FeatureCell that encountered an error.
|
|
1301
|
+
* @param error - The normalized error associated with the failed execution.
|
|
1302
|
+
*/
|
|
1303
|
+
emitError(cellKey: string, error: VaultErrorShape): void;
|
|
1304
|
+
}
|
|
1305
|
+
|
|
1306
|
+
/**
|
|
1307
|
+
* Represents the value passed into persistence behaviors.
|
|
1308
|
+
*
|
|
1309
|
+
* A `PipelinePersistValue<T>` may be:
|
|
1310
|
+
* - `T` — the final, post-encryption state ready to be persisted
|
|
1311
|
+
* - `undefined` — indicating that no value should be written to storage
|
|
1312
|
+
*
|
|
1313
|
+
* Unlike upstream pipeline values, persistence values never include
|
|
1314
|
+
* `VAULT_NOOP`, because no-op handling is completed before the persistence
|
|
1315
|
+
* stage begins.
|
|
1316
|
+
*
|
|
1317
|
+
* @typeParam T - The decrypted/plain state type handled by persistence behaviors.
|
|
1318
|
+
*/
|
|
1319
|
+
type PipelinePersistValue<T> = T | undefined;
|
|
1320
|
+
|
|
1321
|
+
interface EncryptBehaviorContract<T> extends BehaviorContract<T> {
|
|
1322
|
+
/**
|
|
1323
|
+
* Encrypts a plain or already-processed state value before persistence.
|
|
1324
|
+
*
|
|
1325
|
+
* @param ctx - The active behavior context for this pipeline execution.
|
|
1326
|
+
* @param current - The current value to encrypt. May be a plain state value
|
|
1327
|
+
* or `undefined` if persistence should be skipped.
|
|
1328
|
+
* @returns The encrypted `PipelinePersistValue<T>`, either synchronously or asynchronously.
|
|
1329
|
+
*/
|
|
1330
|
+
encryptState(ctx: BehaviorContext<T>, current: PipelinePersistValue<T>): Promise<PipelinePersistValue<T>> | PipelinePersistValue<T>;
|
|
1331
|
+
/**
|
|
1332
|
+
* Decrypts a value retrieved from storage.
|
|
1333
|
+
*
|
|
1334
|
+
* @param ctx - The active behavior context associated with this pipeline run.
|
|
1335
|
+
* @param encrypted - A persisted value (possibly `undefined`) to decrypt.
|
|
1336
|
+
* @returns The decrypted `PipelinePersistValue<T>`, either synchronously or asynchronously.
|
|
1337
|
+
*/
|
|
1338
|
+
decryptState(ctx: BehaviorContext<T>, encrypted: PipelinePersistValue<T>): Promise<PipelinePersistValue<T>> | PipelinePersistValue<T>;
|
|
1339
|
+
}
|
|
1340
|
+
|
|
1341
|
+
type PipelineUpstreamValue<T> = T | undefined | typeof VAULT_NOOP | typeof VAULT_CLEAR_STATE | typeof VAULT_CONTINUE;
|
|
1342
|
+
|
|
1343
|
+
interface FilterBehaviorContract<T> extends BehaviorContract<T> {
|
|
1344
|
+
/** Identifies this behavior as a filter behavior. */
|
|
1345
|
+
type: 'filter';
|
|
1346
|
+
applyFilter(current: PipelineUpstreamValue<T>, filter: FilterFunction<T>): PipelineUpstreamValue<T>;
|
|
1347
|
+
}
|
|
1348
|
+
|
|
1349
|
+
/**
|
|
1350
|
+
* Represents the full set of values an interceptor may return to the
|
|
1351
|
+
* orchestrator during the interceptor stage.
|
|
1352
|
+
*
|
|
1353
|
+
* Interceptors may either:
|
|
1354
|
+
*
|
|
1355
|
+
* - forward the original {@link StateInputType} value unchanged,
|
|
1356
|
+
* - replace it with a transformed {@link StateInputType}, or
|
|
1357
|
+
* - return the reserved {@link VAULT_STOP} symbol to indicate that
|
|
1358
|
+
* pipeline execution should halt for the current write operation.
|
|
1359
|
+
*
|
|
1360
|
+
* Returning `VAULT_STOP` instructs the orchestrator to abort further
|
|
1361
|
+
* processing of the incoming state while maintaining deterministic
|
|
1362
|
+
* pipeline flow. This symbol is treated as an explicit control signal
|
|
1363
|
+
* and is not a user-provided state value.
|
|
1364
|
+
*
|
|
1365
|
+
* @typeParam T - The underlying feature state type being processed.
|
|
1366
|
+
*/
|
|
1367
|
+
type InterceptorStateType<T> = StateInputType<T> | typeof VAULT_STOP;
|
|
1368
|
+
|
|
1369
|
+
interface InterceptorBehaviorContract<T> extends BehaviorContract<T> {
|
|
1370
|
+
/**
|
|
1371
|
+
* Applies the interceptor logic for the incoming state packet.
|
|
1372
|
+
*
|
|
1373
|
+
* @param ctx - The behavior execution context containing the incoming
|
|
1374
|
+
* state and lifecycle metadata for the current pipeline operation.
|
|
1375
|
+
* @returns A promise that resolves to a transformed or replacement
|
|
1376
|
+
* {@link StateInputType} value, or `undefined` when no modification is
|
|
1377
|
+
* necessary.
|
|
1378
|
+
*/
|
|
1379
|
+
applyInterceptor(ctx: BehaviorContext<T>): Promise<InterceptorStateType<T>>;
|
|
1380
|
+
}
|
|
1381
|
+
|
|
1382
|
+
interface MergeBehaviorContract<T> extends BehaviorContract<T> {
|
|
1383
|
+
computeMerge(currentValue: PipelineUpstreamValue<T> | undefined, nextValue: PipelineUpstreamValue<T> | undefined, options?: MergeConfig): PipelineUpstreamValue<T> | undefined;
|
|
1384
|
+
}
|
|
1385
|
+
|
|
1386
|
+
interface OperatorBehaviorContract<T> extends BehaviorContract<T> {
|
|
1387
|
+
applyOperator(value: PipelineUpstreamValue<T>): Promise<PipelineUpstreamValue<T>>;
|
|
1388
|
+
}
|
|
1389
|
+
|
|
1390
|
+
interface PersistBehaviorContract<T> extends BehaviorContract<T> {
|
|
1391
|
+
/** Identifies this behavior as a persistence behavior. */
|
|
1392
|
+
type: 'persist';
|
|
1393
|
+
persistState(current: PipelinePersistValue<T>): Promise<void> | void;
|
|
1394
|
+
clearState(): void;
|
|
1395
|
+
loadState(): PipelinePersistValue<T>;
|
|
1396
|
+
}
|
|
1397
|
+
|
|
1398
|
+
interface ReduceBehaviorContract<T> extends BehaviorContract<T> {
|
|
1399
|
+
/** Pipeline behavior type identifier for reducer-stage execution. */
|
|
1400
|
+
type: 'reduce';
|
|
1401
|
+
/**
|
|
1402
|
+
* Applies the provided reducer function to the current state.
|
|
1403
|
+
*
|
|
1404
|
+
* @param current - The current state value prior to reducer execution.
|
|
1405
|
+
* @param reducer - A pure reducer function returning a new state value.
|
|
1406
|
+
* @returns The transformed state value.
|
|
1407
|
+
*/
|
|
1408
|
+
applyReducer(current: T, reducer: ReducerFunction<T>): T;
|
|
1409
|
+
}
|
|
1410
|
+
|
|
1411
|
+
interface ResolveBehaviorContract<T> extends BehaviorContract<T> {
|
|
1412
|
+
/** Resolve strategy used by this behavior (value, HTTP resource, observable, etc.). */
|
|
1413
|
+
resolveType: 'http-resource' | 'observable' | 'promise' | 'value';
|
|
1414
|
+
computeResolve(ctx: BehaviorContext<T>): Promise<PipelineUpstreamValue<T>> | PipelineUpstreamValue<T>;
|
|
1415
|
+
}
|
|
1416
|
+
|
|
1417
|
+
interface StepwiseBehaviorContract<T> extends BehaviorContract<T> {
|
|
1418
|
+
evaluateStepwise(current: T | undefined, candidate: PipelineUpstreamValue<T>, pipelineId: string): Promise<PipelineUpstreamValue<T>>;
|
|
1419
|
+
}
|
|
1420
|
+
|
|
1421
|
+
interface AfterTapBehaviorContract<T> extends BehaviorContract<T> {
|
|
1422
|
+
applyAfterTap(current: PipelineUpstreamValue<T>, tap: TapCallback<T>): void;
|
|
1423
|
+
}
|
|
1424
|
+
|
|
1425
|
+
interface BeforeTapBehaviorContract<T> extends BehaviorContract<T> {
|
|
1426
|
+
applyBeforeTap(current: PipelineUpstreamValue<T>, tap: TapCallback<T>): void;
|
|
1427
|
+
}
|
|
1428
|
+
|
|
1429
|
+
interface ControllerClassContract<T = any> {
|
|
1430
|
+
new (controllerKey: string, controllerCtx: ControllerClassContext): ControllerContract<T>;
|
|
1431
|
+
readonly type: ControllerType;
|
|
1432
|
+
readonly key: string;
|
|
1433
|
+
readonly critical: boolean;
|
|
1434
|
+
installFluentApi?: <T>(cell: FeatureCellBaseShape<T>, behaviorConfigs: Map<string, unknown>) => void;
|
|
1435
|
+
}
|
|
1436
|
+
|
|
1437
|
+
declare const EventBoundaryTypes: {
|
|
1438
|
+
readonly End: "end";
|
|
1439
|
+
readonly Notification: "notification";
|
|
1440
|
+
readonly Start: "start";
|
|
1441
|
+
readonly Unknown: "unknown";
|
|
1442
|
+
};
|
|
1443
|
+
type EventBoundaryType = (typeof EventBoundaryTypes)[keyof typeof EventBoundaryTypes];
|
|
1444
|
+
|
|
1445
|
+
declare const EventTypes: {
|
|
1446
|
+
readonly Conductor: "conductor";
|
|
1447
|
+
readonly Controller: "controller";
|
|
1448
|
+
readonly Lifecycle: "lifecycle";
|
|
1449
|
+
readonly Stage: "stage";
|
|
1450
|
+
readonly Unknown: "unknown";
|
|
1451
|
+
};
|
|
1452
|
+
type EventType = (typeof EventTypes)[keyof typeof EventTypes];
|
|
1453
|
+
|
|
1454
|
+
/**
|
|
1455
|
+
* Describes the shape of a pipeline event emitted during FeatureCell execution.
|
|
1456
|
+
* This interface defines the core event contract used for diagnostics, Devtools inspection, and lifecycle tracking.
|
|
1457
|
+
*
|
|
1458
|
+
* --RelatedStart--
|
|
1459
|
+
* StateSnapshotShape
|
|
1460
|
+
* --RelatedEnd--
|
|
1461
|
+
*/
|
|
1462
|
+
interface EventShape<T = any> {
|
|
1463
|
+
/**
|
|
1464
|
+
* Unique identifier for the emitted event.
|
|
1465
|
+
*/
|
|
1466
|
+
id: string;
|
|
1467
|
+
/**
|
|
1468
|
+
* The behavior key that produced the event.
|
|
1469
|
+
*/
|
|
1470
|
+
behaviorKey: string;
|
|
1471
|
+
/**
|
|
1472
|
+
* Identifier of the FeatureCell associated with the event.
|
|
1473
|
+
*/
|
|
1474
|
+
cell: string;
|
|
1475
|
+
/**
|
|
1476
|
+
* Optional error information associated with a failure event.
|
|
1477
|
+
*/
|
|
1478
|
+
error?: any;
|
|
1479
|
+
/**
|
|
1480
|
+
* Optional payload associated with the event.
|
|
1481
|
+
*/
|
|
1482
|
+
payload?: unknown;
|
|
1483
|
+
/**
|
|
1484
|
+
* Timestamp indicating when the event occurred.
|
|
1485
|
+
*/
|
|
1486
|
+
timestamp: number;
|
|
1487
|
+
/**
|
|
1488
|
+
* Trace identifier used for Devtools debugging and correlation.
|
|
1489
|
+
*/
|
|
1490
|
+
traceId?: string;
|
|
1491
|
+
/**
|
|
1492
|
+
* The event name describing the lifecycle transition or action.
|
|
1493
|
+
*/
|
|
1494
|
+
name: string;
|
|
1495
|
+
type: EventType;
|
|
1496
|
+
/**
|
|
1497
|
+
* The event boundary type.
|
|
1498
|
+
*/
|
|
1499
|
+
boundary: EventBoundaryType;
|
|
1500
|
+
/**
|
|
1501
|
+
* Optional partial snapshot of FeatureCell state at the time of emission.
|
|
1502
|
+
*/
|
|
1503
|
+
state?: Partial<StateSnapshotShape<T>>;
|
|
1504
|
+
/**
|
|
1505
|
+
* Optional source identifier provided by the event origin.
|
|
1506
|
+
*/
|
|
1507
|
+
source?: string;
|
|
1508
|
+
}
|
|
1509
|
+
|
|
1510
|
+
/**
|
|
1511
|
+
* Defines the contract for an event bus responsible for emitting and observing pipeline and queue events.
|
|
1512
|
+
* This interface provides methods for publishing events and subscribing to their corresponding event streams.
|
|
1513
|
+
*
|
|
1514
|
+
* --RelatedStart--
|
|
1515
|
+
* EventShape
|
|
1516
|
+
* EventQueueShape
|
|
1517
|
+
* --RelatedEnd--
|
|
1518
|
+
*/
|
|
1519
|
+
interface EventBusContract {
|
|
1520
|
+
/**
|
|
1521
|
+
* Emits a pipeline event to all subscribed observers.
|
|
1522
|
+
*
|
|
1523
|
+
* @param event Pipeline event instance to be dispatched.
|
|
1524
|
+
*/
|
|
1525
|
+
nextPipeline(event: EventShape): void;
|
|
1526
|
+
/**
|
|
1527
|
+
* Provides an observable stream of emitted pipeline events.
|
|
1528
|
+
*
|
|
1529
|
+
* @returns Observable stream of pipeline events.
|
|
1530
|
+
*/
|
|
1531
|
+
pipeline$(): Observable<EventShape>;
|
|
1532
|
+
}
|
|
1533
|
+
|
|
1534
|
+
interface VaultErrorServiceContract {
|
|
1535
|
+
readonly error$: Observable<VaultErrorShape | null>;
|
|
1536
|
+
clear(): void;
|
|
1537
|
+
get hasError(): boolean;
|
|
1538
|
+
}
|
|
1539
|
+
|
|
1540
|
+
interface VaultPrivateErrorServiceContract {
|
|
1541
|
+
setError(error: VaultErrorShape | null): void;
|
|
1542
|
+
getError(): Observable<VaultErrorShape | null>;
|
|
1543
|
+
clear(): void;
|
|
1544
|
+
}
|
|
1545
|
+
|
|
1546
|
+
declare function VaultErrorService(): VaultErrorServiceContract;
|
|
1547
|
+
|
|
1548
|
+
declare function VaultPrivateErrorService(): VaultPrivateErrorServiceContract;
|
|
1549
|
+
|
|
1550
|
+
declare const VaultRegistrationLicenseStatusTypes: {
|
|
1551
|
+
readonly NotRequired: "not-required";
|
|
1552
|
+
readonly Pending: "pending";
|
|
1553
|
+
readonly Revoked: "revoked";
|
|
1554
|
+
readonly Timeout: "timeout";
|
|
1555
|
+
readonly Valid: "valid";
|
|
1556
|
+
};
|
|
1557
|
+
type VaultRegistrationLicenseStatusType = (typeof VaultRegistrationLicenseStatusTypes)[keyof typeof VaultRegistrationLicenseStatusTypes];
|
|
1558
|
+
|
|
1559
|
+
interface VaultRegistrationEntityShape {
|
|
1560
|
+
key: string;
|
|
1561
|
+
type: string;
|
|
1562
|
+
critical?: boolean;
|
|
1563
|
+
needsLicense?: boolean;
|
|
1564
|
+
validLicense?: VaultRegistrationLicenseStatusType;
|
|
1565
|
+
licenseId?: string;
|
|
1566
|
+
}
|
|
1567
|
+
|
|
1568
|
+
interface VaultRegistrationFluentApiShape {
|
|
1569
|
+
filters: number;
|
|
1570
|
+
reducers: number;
|
|
1571
|
+
beforeTaps: number;
|
|
1572
|
+
afterTaps: number;
|
|
1573
|
+
emitStateCallbacks: number;
|
|
1574
|
+
errorCallbacks: number;
|
|
1575
|
+
}
|
|
1576
|
+
|
|
1577
|
+
interface VaultRegistrationShape {
|
|
1578
|
+
key: string;
|
|
1579
|
+
vaultSettled?: () => Promise<void>;
|
|
1580
|
+
behaviors?: Map<string, VaultRegistrationEntityShape>;
|
|
1581
|
+
controllers?: Map<string, VaultRegistrationEntityShape>;
|
|
1582
|
+
fluentApis?: Readonly<VaultRegistrationFluentApiShape>;
|
|
1583
|
+
behaviorsRegistered?: boolean;
|
|
1584
|
+
controllersRegistered?: boolean;
|
|
1585
|
+
}
|
|
1586
|
+
|
|
1587
|
+
interface SDuXShape {
|
|
1588
|
+
/**
|
|
1589
|
+
* Global Vault monitor instance.
|
|
1590
|
+
*/
|
|
1591
|
+
vaultMonitorInstance?: VaultMonitorContract;
|
|
1592
|
+
/**
|
|
1593
|
+
* Global Vault event bus instance.
|
|
1594
|
+
*/
|
|
1595
|
+
vaultEventBus?: EventBusContract;
|
|
1596
|
+
debugWidget?: {
|
|
1597
|
+
versions?: Record<string, string>;
|
|
1598
|
+
injected?: boolean;
|
|
1599
|
+
getRegistry?: () => ReadonlyMap<string, VaultRegistrationShape>;
|
|
1600
|
+
};
|
|
1601
|
+
}
|
|
1602
|
+
|
|
1603
|
+
/**
|
|
1604
|
+
* Comparison function used by withDistinctUntilChanged to determine
|
|
1605
|
+
* whether the new incoming value should be considered equal to the
|
|
1606
|
+
* previously emitted value.
|
|
1607
|
+
*
|
|
1608
|
+
* @typeParam T - The value type being compared.
|
|
1609
|
+
*/
|
|
1610
|
+
type DistinctComparison<T> = (a: T, b: T) => boolean;
|
|
1611
|
+
|
|
1612
|
+
/**
|
|
1613
|
+
* Represents the final UI-facing value flowing out of a FeatureCell.
|
|
1614
|
+
*
|
|
1615
|
+
* A `PipelineValue<T>` is the resolved form of state after all
|
|
1616
|
+
* pipeline stages
|
|
1617
|
+
*
|
|
1618
|
+
* Unlike internal pipeline values, this UI-facing type never includes
|
|
1619
|
+
*
|
|
1620
|
+
* @typeParam T - The underlying state type maintained by the FeatureCell.
|
|
1621
|
+
*/
|
|
1622
|
+
type PipelineValue<T> = T | undefined;
|
|
1623
|
+
|
|
1624
|
+
type FinalState<T> = PipelineUpstreamValue<T> | typeof VAULT_STOP;
|
|
1625
|
+
|
|
1626
|
+
/**
|
|
1627
|
+
* Creates a normalized behavior key identifier used for behavior registration.
|
|
1628
|
+
*
|
|
1629
|
+
* A behavior key uniquely identifies a behavior within the Vault pipeline,
|
|
1630
|
+
* following the canonical format:
|
|
1631
|
+
*
|
|
1632
|
+
* `SDUX::<Domain>::<Name>`
|
|
1633
|
+
*
|
|
1634
|
+
* Both `domain` and `name` are normalized by:
|
|
1635
|
+
* - capitalizing the first character
|
|
1636
|
+
* - removing all non-alphanumeric characters
|
|
1637
|
+
*
|
|
1638
|
+
* This ensures consistent and predictable behavior keys for orchestration,
|
|
1639
|
+
* diagnostics, and tooling.
|
|
1640
|
+
*
|
|
1641
|
+
* @param domain - The logical domain or category of the behavior.
|
|
1642
|
+
* @param name - The specific behavior name within the domain.
|
|
1643
|
+
* @returns A normalized behavior key string.
|
|
1644
|
+
*/
|
|
1645
|
+
declare function defineBehaviorKey(domain: string, name: string): string;
|
|
1646
|
+
/**
|
|
1647
|
+
* Validates whether a string conforms to the Vault behavior key format.
|
|
1648
|
+
*
|
|
1649
|
+
* A valid behavior key must follow the structure:
|
|
1650
|
+
*
|
|
1651
|
+
* `SDUX::<Domain>::<Name>`
|
|
1652
|
+
*
|
|
1653
|
+
* Where `<Domain>` and `<Name>` begin with an uppercase character and contain
|
|
1654
|
+
* only alphanumeric characters.
|
|
1655
|
+
*
|
|
1656
|
+
* @param key - The behavior key string to validate.
|
|
1657
|
+
* @returns `true` if the key matches the required pattern; otherwise `false`.
|
|
1658
|
+
*/
|
|
1659
|
+
declare function validateBehaviorKey(key: string): boolean;
|
|
1660
|
+
|
|
1661
|
+
declare function defineControllerKey(domain: string, name: string): string;
|
|
1662
|
+
declare function validateControllerKey(key: string): boolean;
|
|
1663
|
+
|
|
1664
|
+
declare function isDeferredFactory<T = unknown>(value: unknown): value is DeferredFactory<T>;
|
|
1665
|
+
|
|
1666
|
+
declare const DevMode: {
|
|
1667
|
+
readonly active: boolean;
|
|
1668
|
+
setDevMode(isDevMode: boolean): void;
|
|
1669
|
+
};
|
|
1670
|
+
|
|
1671
|
+
declare const isTestEnv: {
|
|
1672
|
+
readonly active: boolean;
|
|
1673
|
+
};
|
|
1674
|
+
|
|
1675
|
+
/**
|
|
1676
|
+
* Normalizes any thrown error into a canonical `VaultError` structure.
|
|
1677
|
+
*
|
|
1678
|
+
* This ensures that all errors—HTTP, runtime, string, or unknown—
|
|
1679
|
+
* are represented consistently throughout the Vault error pipeline.
|
|
1680
|
+
*
|
|
1681
|
+
* @param err - The raw thrown value.
|
|
1682
|
+
* @param featureCellKey - the origination of the error
|
|
1683
|
+
* @returns A fully normalized `VaultError`.
|
|
1684
|
+
*/
|
|
1685
|
+
declare function createVaultError(err: unknown, featureCellKey: string): VaultErrorShape;
|
|
1686
|
+
|
|
1687
|
+
declare const isolateValue: <T>(value: T) => T;
|
|
1688
|
+
|
|
1689
|
+
/**
|
|
1690
|
+
* Emits an `error`-level Vault log message.
|
|
1691
|
+
*
|
|
1692
|
+
* @param args - Console arguments to log.
|
|
1693
|
+
*/
|
|
1694
|
+
declare const vaultError: (...args: any[]) => void;
|
|
1695
|
+
/**
|
|
1696
|
+
* Emits a `warn`-level Vault log message.
|
|
1697
|
+
*
|
|
1698
|
+
* @param args - Console arguments to log.
|
|
1699
|
+
*/
|
|
1700
|
+
declare const vaultWarn: (...args: any[]) => void;
|
|
1701
|
+
/**
|
|
1702
|
+
* Emits a `log`-level Vault log message.
|
|
1703
|
+
*
|
|
1704
|
+
* @param args - Console arguments to log.
|
|
1705
|
+
*/
|
|
1706
|
+
declare const vaultLog: (...args: any[]) => void;
|
|
1707
|
+
/**
|
|
1708
|
+
* Emits a `debug`-level Vault log message.
|
|
1709
|
+
*
|
|
1710
|
+
* @param args - Console arguments to log.
|
|
1711
|
+
*/
|
|
1712
|
+
declare const vaultDebug: (...args: any[]) => void;
|
|
1713
|
+
declare function setVaultLogLevel(level: LogLevelType): void;
|
|
1714
|
+
declare function getVaultLogLevel(): LogLevelType;
|
|
1715
|
+
|
|
1716
|
+
/**
|
|
1717
|
+
* Indicates whether a final pipeline value represents a NOOP condition.
|
|
1718
|
+
*
|
|
1719
|
+
* @param current - The computed pipeline result.
|
|
1720
|
+
* @returns `true` if the value is the `VAULT_NOOP` sentinel.
|
|
1721
|
+
*/
|
|
1722
|
+
declare const isVaultNoop: <T>(current: FinalState<T>) => boolean;
|
|
1723
|
+
declare const isVaultClearState: <T>(current: FinalState<T>) => boolean;
|
|
1724
|
+
declare const isVaultContinue: <T>(current: FinalState<T>) => boolean;
|
|
1725
|
+
/**
|
|
1726
|
+
* Checks whether a value is exactly `null`.
|
|
1727
|
+
*
|
|
1728
|
+
* @param current - The value to check.
|
|
1729
|
+
* @returns `true` if the value is `null`.
|
|
1730
|
+
*/
|
|
1731
|
+
declare const isNull: (current: unknown) => current is null;
|
|
1732
|
+
/**
|
|
1733
|
+
* Checks whether a value is exactly `undefined`.
|
|
1734
|
+
*
|
|
1735
|
+
* @param current - The value to check.
|
|
1736
|
+
* @returns `true` if the value is `undefined`.
|
|
1737
|
+
*/
|
|
1738
|
+
declare const isUndefined: (current: unknown) => current is undefined;
|
|
1739
|
+
/**
|
|
1740
|
+
* Determines whether a value is defined (not `undefined`).
|
|
1741
|
+
* Note: This intentionally does *not* exclude `null`.
|
|
1742
|
+
*
|
|
1743
|
+
* @param current - The value to check.
|
|
1744
|
+
* @returns `true` if the value is not `undefined`.
|
|
1745
|
+
*/
|
|
1746
|
+
declare const isDefined: (current: unknown) => boolean;
|
|
1747
|
+
/**
|
|
1748
|
+
* Determines whether a value is nullish — meaning either `null` or `undefined`.
|
|
1749
|
+
*
|
|
1750
|
+
* @param current - The value to inspect.
|
|
1751
|
+
* @returns `true` for `null` or `undefined`, otherwise `false`.
|
|
1752
|
+
*/
|
|
1753
|
+
declare const isNullish: (current: unknown) => current is null | undefined;
|
|
1754
|
+
declare const isFunction: (value: unknown) => value is (...args: any[]) => unknown;
|
|
1755
|
+
declare const isObject: (value: unknown) => value is Record<string, unknown>;
|
|
1756
|
+
declare const isStateInputShape: <T>(value: unknown) => value is StateInputShape<T>;
|
|
1757
|
+
|
|
1758
|
+
declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
|
|
1759
|
+
|
|
1760
|
+
/**
|
|
1761
|
+
* Type guard that determines whether a value is an `HttpResourceRef<T>`.
|
|
1762
|
+
*
|
|
1763
|
+
* An `HttpResourceRef` is a structured object produced by Angular’s
|
|
1764
|
+
* `HttpClient` resource APIs. It contains a standardized shape used by
|
|
1765
|
+
* Vault to detect and normalize resource-backed state transitions.
|
|
1766
|
+
*
|
|
1767
|
+
* This utility checks only for the presence of the canonical
|
|
1768
|
+
* `HttpResourceRef` fields (`value`, `isLoading`, `error`, `hasValue`)
|
|
1769
|
+
* and does not validate the internal content of those properties.
|
|
1770
|
+
*
|
|
1771
|
+
* @typeParam T - The resource value type.
|
|
1772
|
+
*
|
|
1773
|
+
* @param obj - The value to test.
|
|
1774
|
+
* @returns `true` if the value matches the structural shape of an
|
|
1775
|
+
* `HttpResourceRef<T>`, otherwise `false`.
|
|
1776
|
+
*/
|
|
1777
|
+
declare function isHttpResourceRef<T>(obj: any): obj is HttpResourceRefShape<T>;
|
|
1778
|
+
|
|
1779
|
+
/**
|
|
1780
|
+
* Safely converts an arbitrary value into a JSON string representation.
|
|
1781
|
+
*
|
|
1782
|
+
* This function wraps `JSON.stringify` with enhanced handling for non-serializable
|
|
1783
|
+
* values, including:
|
|
1784
|
+
* - functions
|
|
1785
|
+
* - `Error` objects
|
|
1786
|
+
* - `Map` and `Set` instances
|
|
1787
|
+
* - circular references
|
|
1788
|
+
*
|
|
1789
|
+
* If serialization fails for any reason, a fallback string `"[unserializable]"`
|
|
1790
|
+
* is returned. The replacer ensures stable and predictable stringification for
|
|
1791
|
+
* use in logging and debugging utilities.
|
|
1792
|
+
*
|
|
1793
|
+
* @param value - The value to stringify safely.
|
|
1794
|
+
* @returns A JSON-formatted string or a fallback indicator.
|
|
1795
|
+
*/
|
|
1796
|
+
declare function safeStringify(value: unknown): string;
|
|
1797
|
+
|
|
1798
|
+
declare const registerVersion: (packageName: string, version: string) => void;
|
|
1799
|
+
|
|
1800
|
+
export { AbstractActiveController, AbstractErrorCallbackBehavior, AbstractErrorTransformBehavior, BEHAVIOR_META, BehaviorTypes, CONTROLLER_META, ControllerMessageTypes, ControllerTypes, ControllerVotes, DEVTOOLS_AGGREGATE_KEY_CONSTANT, DEVTOOLS_LOGGING_KEY_CONSTANT, DecisionOutcomeTypes, DevMode, EventBoundaryTypes, EventTypes, LogLevelTypes, OperationTypes, ResolveTypes, StateEmitTypes, VAULT_CLEAR_STATE, VAULT_CONTINUE, VAULT_NOOP, VAULT_STOP, VaultBehavior, VaultController, VaultEncryptionIntegrityError, VaultError, VaultErrorKindTypes, VaultErrorNameTypes, VaultErrorService, VaultErrorUsageKindTypes, VaultLicenseError, VaultPrivateErrorService, VaultUsageError, VaultUsagePromiseError, VaultUsagePromiseFactoryRequiredError, createVaultError, defineBehaviorKey, defineControllerKey, getVaultLogLevel, isDeferredFactory, isDefined, isFunction, isHttpResourceRef, isNull, isNullish, isObject, isPromise, isStateInputShape, isTestEnv, isUndefined, isVaultClearState, isVaultContinue, isVaultNoop, isolateValue, registerVersion, safeStringify, setVaultLogLevel, validateBehaviorKey, validateControllerKey, vaultDebug, vaultError, vaultLog, vaultWarn };
|
|
1801
|
+
export type { AfterTapBehaviorContract, BeforeTapBehaviorContract, BehaviorClassContext, BehaviorClassContract, BehaviorContext, BehaviorContract, BehaviorExtFunction, BehaviorExtension, BehaviorMetaShape, BehaviorType, CellBuilderContract, ControllerAttemptMessageShape, ControllerClassContext, ControllerClassContract, ControllerContext, ControllerContract, ControllerDecisionShape, ControllerFailMessageShape, ControllerFinalizeMessageShape, ControllerMessageShape, ControllerMessageType, ControllerMetaShape, ControllerSuccessMessageShape, ControllerType, ControllerVote, CoreEmitStateBehaviorContract, CoreEmitStateCallback, CoreEmitStateResult, DecisionOutcomeType, DeferredFactory, DeferredType, DevPipelineObserverBehaviorContract, DistinctComparison, EncryptBehaviorContract, ErrorCallbackBehaviorContract, ErrorTransformBehaviorContract, EventBoundaryType, EventBusContract, EventShape, EventType, FeatureCellBaseShape, FeatureCellExtension, FeatureCellExtensionContext, FeatureCellFluentApi, FilterBehaviorContract, FilterFunction, FinalState, HttpResourceRefShape, InsightConfig, InterceptorBehaviorClassContract, InterceptorBehaviorContract, InterceptorStateType, LogLevelType, MergeBehaviorContract, MergeConfig, ObjectDeepMergeConfig, OperationType, OperatorBehaviorContract, OperatorsBehaviorClassContract, PersistBehaviorContract, PipelinePersistValue, PipelineUpstreamValue, PipelineValue, ReduceBehaviorContract, ReducerFunction, ResolveBehaviorContract, ResolveType, SDuXShape, StateEmitSnapshotShape, StateEmitType, StateInputShape, StateInputType, StateSnapshotShape, StepwiseBehaviorContract, TapCallback, VaultConfig, VaultErrorCallback, VaultErrorKindType, VaultErrorNameType, VaultErrorServiceContract, VaultErrorShape, VaultErrorUsageKindType, VaultLicensingShape, VaultMonitorContract, VaultPrivateErrorServiceContract, VaultRegistrationEntityShape, VaultRegistrationFluentApiShape, VaultRegistrationShape };
|