@deviltea/widget-core 0.0.5 → 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/README.md +250 -62
- package/dist/{dep-Cvv2QPKi.d.mts → dep-BXcdMm-M.d.mts} +309 -84
- package/dist/event-Bk-mkL1E.mjs +956 -0
- package/dist/index.d.mts +93 -12
- package/dist/index.mjs +1921 -659
- package/dist/inspection/index.d.mts +35 -3
- package/dist/inspection/index.mjs +23 -2
- package/dist/integration/index.d.mts +8 -2
- package/dist/integration/index.mjs +11 -3
- package/dist/internals-CVKUQDIN.mjs +388 -0
- package/package.json +3 -2
- package/dist/event-BMif_vRJ.mjs +0 -192
- package/dist/internals-L391flXY.mjs +0 -199
|
@@ -10,13 +10,30 @@ interface JsonObject {
|
|
|
10
10
|
readonly [key: string]: JsonValue;
|
|
11
11
|
}
|
|
12
12
|
type JsonValue = JsonPrimitive | JsonArray | JsonObject;
|
|
13
|
+
/**
|
|
14
|
+
* The maximum JSON nesting depth of authored source and SourcePatch operands: the number of containers
|
|
15
|
+
* (objects and arrays) a value may be nested inside, counting the value's own container. A value nested
|
|
16
|
+
* deeper is outside the JSON domain (`json-incompatible-value`, reason `max-depth-exceeded`) and is never
|
|
17
|
+
* descended into, so arbitrarily deep input yields a diagnostic or an operation failure instead of exhausting
|
|
18
|
+
* the call stack. A widget node nests three containers per tree level (node, `slots`, slot Array), so the
|
|
19
|
+
* limit allows widget trees about 85 levels deep. The value leaves a wide margin below the call-stack limit of
|
|
20
|
+
* Node 22/24 and of smaller-stack embedded engines, and is part of the public contract.
|
|
21
|
+
*/
|
|
22
|
+
declare const MAX_JSON_DEPTH = 256;
|
|
23
|
+
declare function isJsonValue(value: unknown): value is JsonValue;
|
|
13
24
|
/**
|
|
14
25
|
* Type-level diagnostic for a RawConfig that is not statically within JsonValue. Optional properties
|
|
15
26
|
* are allowed to be omitted, but an explicitly required `undefined` remains outside the domain.
|
|
16
27
|
*/
|
|
17
|
-
type IsAny$
|
|
28
|
+
type IsAny$2<T> = 0 extends 1 & T ? true : false;
|
|
18
29
|
type OptionalKeys<T extends object> = { [Key in keyof T]-?: Record<never, never> extends Pick<T, Key> ? Key : never; }[keyof T];
|
|
19
|
-
|
|
30
|
+
/**
|
|
31
|
+
* Well-known-symbol members that only class instances carry (`Date`, `Map`, `Set`, iterables, ...).
|
|
32
|
+
* Checked before the string-key rule, so such a value reports the non-plain-object reason instead of
|
|
33
|
+
* "may only have string keys".
|
|
34
|
+
*/
|
|
35
|
+
type ClassInstanceSymbolKey = typeof Symbol.iterator | typeof Symbol.asyncIterator | typeof Symbol.toPrimitive | typeof Symbol.toStringTag;
|
|
36
|
+
type JsonDomainViolation<Value> = IsAny$2<Value> extends true ? 'authored JSON values cannot contain any' : [Value] extends [never] ? never : [Value] extends [JsonValue] ? never : Value extends string | number | boolean | null ? never : Value extends ((...args: any[]) => any) ? 'authored values must be JSON-compatible' : Value extends readonly (infer Element)[] ? JsonDomainViolation<Element> : Value extends object ? [Extract<keyof Value, ClassInstanceSymbolKey>] extends [never] ? Exclude<keyof Value, string> extends never ? { [Key in keyof Value]-?: Key extends OptionalKeys<Value> ? JsonDomainViolation<Exclude<Value[Key], undefined>> : JsonDomainViolation<Value[Key]>; }[keyof Value] : 'authored JSON objects may only have string keys' : 'authored JSON objects must be plain objects, not class instances such as Date, Map or Set' : 'authored values must be JSON-compatible';
|
|
20
37
|
//#endregion
|
|
21
38
|
//#region src/types.d.ts
|
|
22
39
|
/**
|
|
@@ -53,7 +70,7 @@ interface WidgetInterfaces {
|
|
|
53
70
|
* A readonly array that is non-empty when present. Used by every optional `related` collection.
|
|
54
71
|
*/
|
|
55
72
|
type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
|
|
56
|
-
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
73
|
+
type IsAny$1<T> = 0 extends 1 & T ? true : false;
|
|
57
74
|
/**
|
|
58
75
|
* Reads one declared capability. Returns `never` when the capability is absent.
|
|
59
76
|
*
|
|
@@ -104,7 +121,7 @@ type WidgetMethodOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemb
|
|
|
104
121
|
type WidgetMethodArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Parameters<WidgetMethodOf<Interfaces, Name>>;
|
|
105
122
|
type WidgetMethodReturnOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = ReturnType<WidgetMethodOf<Interfaces, Name>>;
|
|
106
123
|
type WidgetEventArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Extract<WidgetMemberValueOf<WidgetEventsOf<Interfaces>, Name>, readonly any[]>;
|
|
107
|
-
type ContainsPromiseLike<Value> = IsAny<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
|
|
124
|
+
type ContainsPromiseLike<Value> = IsAny$1<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
|
|
108
125
|
type MemberKeyDomainViolation<Section extends string, Members> = [Members] extends [never] ? never : [keyof Members] extends [never] ? never : [keyof Members] extends [WidgetMemberKey] ? WidgetMemberKey extends keyof Members ? `'${Section}' must not be declared with a broad string index signature` : never : `'${Section}' member keys must be finite string literals`;
|
|
109
126
|
type SyncValueDomainViolation<Section extends string, Members> = [Members] extends [never] ? never : true extends { [Key in keyof Members]-?: ContainsPromiseLike<Members[Key]>; }[keyof Members] ? `'${Section}' values must not be PromiseLike; the core semantic boundary is synchronous` : never;
|
|
110
127
|
type SyncMethodReturnViolation<Interfaces extends WidgetInterfaces> = WidgetMethodsOf<Interfaces> extends (infer Methods) ? [Methods] extends [never] ? never : true extends { [Key in keyof Methods]-?: ContainsPromiseLike<ReturnType<Extract<Methods[Key], (...args: any[]) => any>>>; }[keyof Methods] ? `'methods' return types must not be PromiseLike; the core semantic boundary is synchronous` : never : never;
|
|
@@ -151,11 +168,18 @@ declare const widgetValueContractType: unique symbol;
|
|
|
151
168
|
*
|
|
152
169
|
* The generic parameter exists only for Plugin-author type safety. Runtime/integration identity is the
|
|
153
170
|
* stable string `id`; descriptor object identity has no semantic meaning.
|
|
171
|
+
*
|
|
172
|
+
* A contract for `Value` describes every value of that type, so it can be attached to a Property whose
|
|
173
|
+
* value type is the same or narrower (every value the Property produces satisfies the contract):
|
|
174
|
+
* `WidgetValueContract<string>` fits a `'small' | 'large'` Property, but not a `string | null` one.
|
|
154
175
|
*/
|
|
155
176
|
interface WidgetValueContract<Value> {
|
|
156
177
|
readonly id: string;
|
|
157
|
-
/**
|
|
158
|
-
|
|
178
|
+
/**
|
|
179
|
+
* Type-only contravariant brand (`WidgetValueContract<Wide>` is assignable to
|
|
180
|
+
* `WidgetValueContract<Narrow>`); the factory-created runtime descriptor contains only `id`.
|
|
181
|
+
*/
|
|
182
|
+
readonly [widgetValueContractType]: (value: Value) => void;
|
|
159
183
|
}
|
|
160
184
|
/**
|
|
161
185
|
* Declares a stable semantic value-contract id while retaining the associated TypeScript value type for
|
|
@@ -190,6 +214,8 @@ interface ErasedWidgetPropertyDefinition {
|
|
|
190
214
|
interface ErasedWidgetMethodDefinition {
|
|
191
215
|
readonly registerDeps?: (ctx: any) => RegisteredDeps;
|
|
192
216
|
readonly validateArgs: (args: readonly unknown[], ctx: any) => boolean;
|
|
217
|
+
/** The declared Events, a frozen copy; checked against the events section by `done()`. */
|
|
218
|
+
readonly emits?: readonly WidgetMemberKey[];
|
|
193
219
|
readonly execute: (ctx: any) => unknown;
|
|
194
220
|
}
|
|
195
221
|
interface ErasedWidgetEventDefinition {
|
|
@@ -234,14 +260,19 @@ interface WidgetPluginCapabilities {
|
|
|
234
260
|
readonly methods: boolean;
|
|
235
261
|
readonly events: boolean;
|
|
236
262
|
}
|
|
237
|
-
/**
|
|
238
|
-
* A completed plugin. Plugin-specific integration options are captured by the plugin factory's
|
|
239
|
-
* closure; there is no `pluginConfig` / `globalConfig`.
|
|
240
|
-
*/
|
|
263
|
+
/** Passive RawConfig authoring metadata of a plugin with a config capability. */
|
|
241
264
|
interface WidgetPluginConfigMetadata {
|
|
242
265
|
readonly description: string;
|
|
243
266
|
readonly schema: WidgetConfigJsonSchema | null;
|
|
244
267
|
}
|
|
268
|
+
/**
|
|
269
|
+
* A completed plugin. Plugin-specific integration options are captured by the plugin factory's
|
|
270
|
+
* closure; there is no `pluginConfig` / `globalConfig`.
|
|
271
|
+
*
|
|
272
|
+
* A completed plugin is immutable: `done()` freezes it, every section builder is sealed once its build
|
|
273
|
+
* callback returns, and every config, slot and member definition was captured by value when declared,
|
|
274
|
+
* so neither a retained builder section nor later mutation of the author's definition objects changes it.
|
|
275
|
+
*/
|
|
245
276
|
interface WidgetPlugin<Type extends string = string, Interfaces extends WidgetInterfaces = WidgetInterfaces> {
|
|
246
277
|
readonly type: Type;
|
|
247
278
|
readonly description: string;
|
|
@@ -291,19 +322,60 @@ type WidgetRegisterDepsContext<Interfaces extends WidgetInterfaces, Consumer ext
|
|
|
291
322
|
} & WidgetResolvedConfigContext<Interfaces>;
|
|
292
323
|
type WidgetPropertyComputeContext<Interfaces extends WidgetInterfaces, Deps extends RegisteredDeps> = {
|
|
293
324
|
readonly widget: SelfBlueprintWidgetNode<Interfaces>;
|
|
294
|
-
readonly blueprint:
|
|
325
|
+
readonly blueprint: BlueprintRuntimeView;
|
|
295
326
|
readonly deps: ToExecutedDeps<Deps, 'property'>;
|
|
296
327
|
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces>;
|
|
297
328
|
type WidgetEventEmitter<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetEventKeyOf<Interfaces>]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
|
|
298
|
-
|
|
299
|
-
|
|
329
|
+
/** The `emit` one Method receives carries exactly the Events it declares in `emits`. */
|
|
330
|
+
type WidgetMethodEventEmitter<Interfaces extends WidgetInterfaces, Emits extends WidgetEventKeyOf<Interfaces>> = { readonly [Name in Emits]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
|
|
331
|
+
type WidgetEventEmitterContext<Interfaces extends WidgetInterfaces, Emits extends WidgetEventKeyOf<Interfaces> = never> = HasWidgetCapability<Interfaces, 'events'> extends true ? {
|
|
332
|
+
readonly emit: WidgetMethodEventEmitter<Interfaces, Emits>;
|
|
300
333
|
} : unknown;
|
|
301
|
-
type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps> = {
|
|
334
|
+
type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Emits extends WidgetEventKeyOf<Interfaces> = never> = {
|
|
302
335
|
readonly args: WidgetMethodArgsOf<Interfaces, Name>;
|
|
303
336
|
readonly widget: SelfBlueprintWidgetNode<Interfaces>;
|
|
304
|
-
readonly blueprint:
|
|
337
|
+
readonly blueprint: BlueprintRuntimeView;
|
|
305
338
|
readonly deps: ToExecutedDeps<Deps, 'method'>;
|
|
306
|
-
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces>;
|
|
339
|
+
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces, Emits>;
|
|
340
|
+
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
341
|
+
type IsExactlyVoid<T> = (<X>() => X extends T ? 1 : 2) extends (<X>() => X extends void ? 1 : 2) ? true : false;
|
|
342
|
+
/**
|
|
343
|
+
* Whether `Value` can be a thenable: anything with a callable `then`, which is what the runtime guard
|
|
344
|
+
* rejects (not only a native `PromiseLike`). An object whose `then` is not a function is not one. For a
|
|
345
|
+
* value of a type parameter the check stays deferred, which TypeScript accepts.
|
|
346
|
+
*/
|
|
347
|
+
type MayBeThenable<Value> = [Extract<Value, {
|
|
348
|
+
readonly then: (...args: never) => unknown;
|
|
349
|
+
}>] extends [never] ? false : true;
|
|
350
|
+
/**
|
|
351
|
+
* What a thenable result is checked against. The `then` text is the compile-error message; no callable
|
|
352
|
+
* `then` satisfies it.
|
|
353
|
+
*/
|
|
354
|
+
interface WidgetSynchronousResultViolation {
|
|
355
|
+
readonly then: 'widget-core: semantic callbacks are synchronous; returning a PromiseLike/thenable is a contract violation';
|
|
356
|
+
}
|
|
357
|
+
/**
|
|
358
|
+
* The return type a semantic callback is checked against, given `Result`, the callback's own return type:
|
|
359
|
+
* `Result` itself unless it can be a thenable. A `void` (or `unknown`) return type cannot do this on its own:
|
|
360
|
+
* TypeScript lets a `void`-returning function type accept any function, an `async` one included, and every
|
|
361
|
+
* value is assignable to `unknown`. Gating on the callback's own return type rejects a thenable while every
|
|
362
|
+
* synchronous value — an `unknown`-typed expression, a value of a type parameter, an object whose `then` is
|
|
363
|
+
* not a function — still type-checks.
|
|
364
|
+
*
|
|
365
|
+
* `Result` is inferred where the callback is written into the builder (a Method's `execute`, a slot's or the
|
|
366
|
+
* plugin's `validateStructure`) or into `createWidgetSystem`'s options. A standalone definition type has no
|
|
367
|
+
* callback to infer from, so `Result` defaults to `unknown` and it accepts any return: a thenable reaching
|
|
368
|
+
* Core through a callback typed only by such an annotation is caught by the runtime guard instead, which
|
|
369
|
+
* throws a `TypeError`.
|
|
370
|
+
*/
|
|
371
|
+
type WidgetSynchronousResult<Result> = Result & (MayBeThenable<Result> extends true ? WidgetSynchronousResultViolation : unknown);
|
|
372
|
+
/**
|
|
373
|
+
* `execute`'s return type for the declared Method return `Declared`. A declared type a thenable is
|
|
374
|
+
* assignable to — exactly `void`, `unknown`, `{}`, `object` — gates on the `execute`'s own return type
|
|
375
|
+
* `Result` (see {@link WidgetSynchronousResult}); any other declared type already rejects a PromiseLike (see
|
|
376
|
+
* `WidgetInterfacesViolationOf`). `any` stays unchecked.
|
|
377
|
+
*/
|
|
378
|
+
type WidgetMethodExecuteResult<Declared, Result> = IsAny<Declared> extends true ? Declared : IsExactlyVoid<Declared> extends true ? WidgetSynchronousResult<Result> : PromiseLike<unknown> extends Declared ? Declared & WidgetSynchronousResult<Result> : Declared;
|
|
307
379
|
interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
|
|
308
380
|
readonly description: string;
|
|
309
381
|
/** Passive Draft 2020-12 authoring metadata. Core does not validate or execute this schema. */
|
|
@@ -311,17 +383,24 @@ interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
|
|
|
311
383
|
readonly validate: (input: unknown, ctx: WidgetConfigValidateContext) => input is WidgetRawConfigOf<Interfaces>;
|
|
312
384
|
readonly resolve: (rawConfig: WidgetRawConfigOf<Interfaces> | null) => WidgetResolvedConfigOf<Interfaces>;
|
|
313
385
|
}
|
|
314
|
-
|
|
386
|
+
/** `Result` is the slot validator's own return type (see {@link WidgetSynchronousResult}). */
|
|
387
|
+
interface WidgetSlotDefinition<Interfaces extends WidgetInterfaces, SlotName extends WidgetMemberKey, Result = unknown> {
|
|
315
388
|
readonly description: string;
|
|
316
|
-
readonly validateStructure?: (ctx: WidgetSlotValidateStructureContext<Interfaces, SlotName>) =>
|
|
389
|
+
readonly validateStructure?: (ctx: WidgetSlotValidateStructureContext<Interfaces, SlotName>) => WidgetSynchronousResult<Result>;
|
|
317
390
|
}
|
|
318
391
|
type WidgetSlotDefinitions<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetSlotNameOf<Interfaces>]: WidgetSlotDefinition<Interfaces, Name>; };
|
|
392
|
+
/** The return type of the `validateStructure` a slots object declares for `Name`, or `unknown`. */
|
|
393
|
+
type WidgetSlotStructureResultOf<Definitions, Name extends PropertyKey> = Definitions extends { readonly [Key in Name]: {
|
|
394
|
+
readonly validateStructure?: (...args: never) => infer Result;
|
|
395
|
+
}; } ? Result : unknown;
|
|
319
396
|
/**
|
|
320
397
|
* Rejects a slots object that carries a slot the interfaces never declared, including when the
|
|
321
|
-
* object is supplied through a variable instead of a fresh object literal
|
|
398
|
+
* object is supplied through a variable instead of a fresh object literal, and a slot validator that
|
|
399
|
+
* returns a thenable.
|
|
322
400
|
*/
|
|
323
|
-
type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> =
|
|
324
|
-
|
|
401
|
+
type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> = { readonly [Name in WidgetSlotNameOf<Interfaces>]: WidgetSlotDefinition<Interfaces, Name, WidgetSlotStructureResultOf<Definitions, Name>>; } & { readonly [Name in keyof Definitions as Name extends WidgetSlotNameOf<Interfaces> ? never : Name]: never; };
|
|
402
|
+
/** `Result` is the validator's own return type (see {@link WidgetSynchronousResult}). */
|
|
403
|
+
type WidgetPluginValidateStructure<Interfaces extends WidgetInterfaces, Result = unknown> = (ctx: WidgetPluginValidateStructureContext<Interfaces>) => WidgetSynchronousResult<Result>;
|
|
325
404
|
interface WidgetStateMemberDefinition<Interfaces extends WidgetInterfaces, Key extends WidgetMemberKey> {
|
|
326
405
|
/** Passive authoring policy. Omitted means this State member is not author-writable. */
|
|
327
406
|
readonly authorWritable?: boolean;
|
|
@@ -334,11 +413,25 @@ interface WidgetPropertyDefinition<Interfaces extends WidgetInterfaces, Name ext
|
|
|
334
413
|
readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'property'>) => Deps;
|
|
335
414
|
readonly compute: (ctx: WidgetPropertyComputeContext<Interfaces, Deps>) => WidgetPropertyValueOf<Interfaces, Name>;
|
|
336
415
|
}
|
|
337
|
-
interface
|
|
416
|
+
interface WidgetMethodDefinitionFields<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Result, Emits extends WidgetEventKeyOf<Interfaces>> {
|
|
338
417
|
readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'method'>) => Deps;
|
|
339
418
|
readonly validateArgs: (args: readonly unknown[], ctx: WidgetMethodValidateArgsContext<Interfaces>) => args is WidgetMethodArgsOf<Interfaces, Name>;
|
|
340
|
-
|
|
419
|
+
/**
|
|
420
|
+
* The Events this Method may emit. Omitted or empty means none. A Method that emits an Event, itself or
|
|
421
|
+
* through the Methods it invokes, is not read-only, so no Property may depend on it.
|
|
422
|
+
*/
|
|
423
|
+
readonly emits?: readonly Emits[];
|
|
424
|
+
readonly execute: (ctx: WidgetMethodExecuteContext<Interfaces, Name, Deps, Emits>) => WidgetMethodExecuteResult<WidgetMethodReturnOf<Interfaces, Name>, Result>;
|
|
341
425
|
}
|
|
426
|
+
/**
|
|
427
|
+
* `Result` is `execute`'s own return type (see {@link WidgetMethodExecuteResult}). `Emits` is the union of
|
|
428
|
+
* the Events the Method declares: whenever it is not `never`, `execute` receives an `emit` with those
|
|
429
|
+
* Events, so `emits` is required (a definition that types `emit` without declaring it would throw at its
|
|
430
|
+
* first emit).
|
|
431
|
+
*/
|
|
432
|
+
type WidgetMethodDefinition<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Result = unknown, Emits extends WidgetEventKeyOf<Interfaces> = never> = WidgetMethodDefinitionFields<Interfaces, Name, Deps, Result, Emits> & ([Emits] extends [never] ? unknown : {
|
|
433
|
+
readonly emits: readonly Emits[];
|
|
434
|
+
});
|
|
342
435
|
interface WidgetEventDefinition {
|
|
343
436
|
readonly description: string;
|
|
344
437
|
}
|
|
@@ -352,7 +445,7 @@ interface WidgetSectionMarker<Kind extends string, Remaining extends WidgetMembe
|
|
|
352
445
|
}
|
|
353
446
|
type WidgetStateSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetStateKeyOf<Interfaces>> = WidgetSectionMarker<'state', Remaining> & { [Key in Remaining]: (definition: WidgetStateMemberDefinition<Interfaces, Key>) => WidgetStateSection<Interfaces, Exclude<Remaining, Key>>; };
|
|
354
447
|
type WidgetPropertiesSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetPropertyKeyOf<Interfaces>> = WidgetSectionMarker<'properties', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps>(definition: WidgetPropertyDefinition<Interfaces, Name, Deps>) => WidgetPropertiesSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
355
|
-
type WidgetMethodsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetMethodKeyOf<Interfaces>> = WidgetSectionMarker<'methods', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps>(definition: WidgetMethodDefinition<Interfaces, Name, Deps>) => WidgetMethodsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
448
|
+
type WidgetMethodsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetMethodKeyOf<Interfaces>> = WidgetSectionMarker<'methods', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps, Result = unknown, const Emits extends WidgetEventKeyOf<Interfaces> = never>(definition: WidgetMethodDefinition<Interfaces, Name, Deps, Result, Emits>) => WidgetMethodsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
356
449
|
type WidgetEventsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetEventKeyOf<Interfaces>> = WidgetSectionMarker<'events', Remaining> & { [Name in Remaining]: (definition: WidgetEventDefinition) => WidgetEventsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
357
450
|
/**
|
|
358
451
|
* Returned instead of the next builder phase when the supplied `WidgetInterfaces` is outside the
|
|
@@ -365,16 +458,21 @@ interface WidgetPluginDonePhase<Type extends string, Interfaces extends WidgetIn
|
|
|
365
458
|
done: () => WidgetPlugin<Type, Interfaces>;
|
|
366
459
|
}
|
|
367
460
|
/**
|
|
368
|
-
* Outer
|
|
369
|
-
* the
|
|
461
|
+
* Outer builder phases in their fixed call order: every capability phase plus the optional,
|
|
462
|
+
* capability-independent `structure` phase. Part of the type-level order diagnostics only; the runtime
|
|
463
|
+
* builder is order-agnostic.
|
|
370
464
|
*/
|
|
371
|
-
type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'state', 'properties', 'methods', 'events'];
|
|
465
|
+
type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'structure', 'state', 'properties', 'methods', 'events'];
|
|
372
466
|
type WidgetPluginPhaseName = WidgetPluginPhaseOrder[number];
|
|
373
|
-
|
|
374
|
-
|
|
467
|
+
type WidgetPluginCapabilityPhaseName = Exclude<WidgetPluginPhaseName, 'structure'>;
|
|
468
|
+
/**
|
|
469
|
+
* The phases available for `Interfaces`: every phase whose capability was declared, plus `structure`,
|
|
470
|
+
* which every plugin may call (at most once) regardless of its capabilities.
|
|
471
|
+
*/
|
|
472
|
+
type WidgetPluginAvailablePhaseName<Interfaces extends WidgetInterfaces> = 'structure' | { [Phase in WidgetPluginCapabilityPhaseName]: HasWidgetCapability<Interfaces, Phase> extends true ? Phase : never; }[WidgetPluginCapabilityPhaseName];
|
|
375
473
|
type WidgetPluginPhaseIsBefore<A extends WidgetPluginPhaseName, B extends WidgetPluginPhaseName, Order extends readonly WidgetPluginPhaseName[] = WidgetPluginPhaseOrder> = Order extends readonly [infer Head, ...infer Tail extends readonly WidgetPluginPhaseName[]] ? Head extends A ? true : Head extends B ? false : WidgetPluginPhaseIsBefore<A, B, Tail> : false;
|
|
376
474
|
/**
|
|
377
|
-
* Type-only order marker: the message of the compile error raised when
|
|
475
|
+
* Type-only order marker: the message of the compile error raised when an available phase is called at
|
|
378
476
|
* the wrong position. The marker name and reason text are diagnostics, not protocol.
|
|
379
477
|
*/
|
|
380
478
|
interface WidgetPluginPhaseOrderViolation<Reason extends string> {
|
|
@@ -386,39 +484,58 @@ interface WidgetPluginPhaseOrderViolation<Reason extends string> {
|
|
|
386
484
|
* reason) in the message, while the function constituent keeps callbacks contextually typed, so no
|
|
387
485
|
* implicit-`any` follow-on errors appear. Section builders may return anything.
|
|
388
486
|
*/
|
|
389
|
-
type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces
|
|
390
|
-
type WidgetPluginPhaseOrderReason<Phase extends WidgetPluginPhaseName, Stage extends WidgetPluginPhaseName | 'done'> = Stage extends WidgetPluginPhaseName ? WidgetPluginPhaseIsBefore<Phase, Stage> extends true ? `'.${Phase}()' was already called or must be called earlier; the next phase is '.${Stage}()'. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' is called too early; call '.${Stage}()' first. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' cannot be called here; the declared phases are already complete, so only '.done()' remains. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
487
|
+
type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces>] : Phase extends 'structure' ? [validateStructure: Violation & WidgetPluginValidateStructure<Interfaces>] : Phase extends 'state' ? [build: Violation & ((section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => unknown)] : Phase extends 'properties' ? [build: Violation & ((section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => unknown)] : Phase extends 'methods' ? [build: Violation & ((section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => unknown)] : [build: Violation & ((section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => unknown)];
|
|
488
|
+
type WidgetPluginPhaseOrderReason<Phase extends WidgetPluginPhaseName, Stage extends WidgetPluginPhaseName | 'done'> = Stage extends WidgetPluginPhaseName ? WidgetPluginPhaseIsBefore<Phase, Stage> extends true ? `'.${Phase}()' was already called or must be called earlier; the next phase is '.${Stage}()'. Order: description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' is called too early; call '.${Stage}()' first. Order: description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' cannot be called here; the declared phases are already complete, so only '.done()' remains. Order: description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
391
489
|
/**
|
|
392
|
-
* Adds type-only order markers for every
|
|
393
|
-
*
|
|
490
|
+
* Adds type-only order markers for every available phase that is not in `Callable` (by default just
|
|
491
|
+
* `Stage`, the next phase; the `structure` stage also keeps the optional `structure` phase callable).
|
|
492
|
+
* A marker takes the real phase's arguments with the first one intersected with
|
|
394
493
|
* `WidgetPluginPhaseOrderViolation`, so no real value satisfies it and the call fails with an
|
|
395
|
-
* order-specific diagnostic (the function constituent keeps a callback passed to it
|
|
396
|
-
* so no implicit-`any` follow-on errors appear). It returns the same phase, so a
|
|
397
|
-
* advances the chain.
|
|
494
|
+
* order-specific diagnostic relative to `Stage` (the function constituent keeps a callback passed to it
|
|
495
|
+
* contextually typed, so no implicit-`any` follow-on errors appear). It returns the same phase, so a
|
|
496
|
+
* misplaced call never advances the chain.
|
|
398
497
|
*/
|
|
399
|
-
type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done'> = [Exclude<
|
|
400
|
-
|
|
498
|
+
type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done', Callable extends WidgetPluginPhaseName | 'done' = Stage> = [Exclude<WidgetPluginAvailablePhaseName<Interfaces>, Callable>] extends [never] ? Phase : Phase & { [Misplaced in Exclude<WidgetPluginAvailablePhaseName<Interfaces>, Callable>]: (...args: WidgetPluginMisplacedArguments<Interfaces, Misplaced, WidgetPluginPhaseOrderViolation<WidgetPluginPhaseOrderReason<Misplaced, Stage>>>) => WidgetPluginOrderedPhase<Phase, Interfaces, Stage, Callable>; };
|
|
499
|
+
interface WidgetPluginEventsPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
401
500
|
events: (build: (section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => WidgetEventsSection<Interfaces, never>) => WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
|
|
402
|
-
}
|
|
403
|
-
|
|
501
|
+
}
|
|
502
|
+
interface WidgetPluginMethodsPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
404
503
|
methods: (build: (section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => WidgetMethodsSection<Interfaces, never>) => WidgetPluginEventsPhase<Type, Interfaces>;
|
|
405
|
-
}
|
|
406
|
-
|
|
504
|
+
}
|
|
505
|
+
interface WidgetPluginPropertiesPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
407
506
|
properties: (build: (section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => WidgetPropertiesSection<Interfaces, never>) => WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
408
|
-
}
|
|
409
|
-
|
|
507
|
+
}
|
|
508
|
+
interface WidgetPluginStatePhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
410
509
|
state: (build: (section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => WidgetStateSection<Interfaces, never>) => WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
411
|
-
}
|
|
510
|
+
}
|
|
511
|
+
type WidgetPluginEventsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginOrderedPhase<WidgetPluginEventsPhaseMembers<Type, Interfaces>, Interfaces, 'events'> : WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
|
|
512
|
+
type WidgetPluginMethodsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginOrderedPhase<WidgetPluginMethodsPhaseMembers<Type, Interfaces>, Interfaces, 'methods'> : WidgetPluginEventsPhase<Type, Interfaces>;
|
|
513
|
+
type WidgetPluginPropertiesPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginOrderedPhase<WidgetPluginPropertiesPhaseMembers<Type, Interfaces>, Interfaces, 'properties'> : WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
514
|
+
type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginOrderedPhase<WidgetPluginStatePhaseMembers<Type, Interfaces>, Interfaces, 'state'> : WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
515
|
+
/**
|
|
516
|
+
* The `structure` stage: the optional `.structure()` call and the first declared phase after it (or
|
|
517
|
+
* `.done()`) are both callable. Order markers report relative to that next phase, since `structure` may
|
|
518
|
+
* be skipped.
|
|
519
|
+
*/
|
|
520
|
+
type WidgetPluginStructureStage<Type extends string, Interfaces extends WidgetInterfaces, Next extends WidgetPluginPhaseName | 'done', NextMembers> = WidgetPluginOrderedPhase<{
|
|
521
|
+
structure: <Result = unknown>(validateStructure: WidgetPluginValidateStructure<Interfaces, Result>) => WidgetPluginStatePhase<Type, Interfaces>;
|
|
522
|
+
} & NextMembers, Interfaces, Next, 'structure' | Next>;
|
|
523
|
+
/**
|
|
524
|
+
* The optional plugin-level structure validator phase. It is not a capability: every plugin may call
|
|
525
|
+
* `.structure(validateStructure)` at most once, after `slots?` and before `state?`, and it changes
|
|
526
|
+
* neither `plugin.capabilities`, the catalog, nor inspection.
|
|
527
|
+
*/
|
|
528
|
+
type WidgetPluginStructurePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'state', WidgetPluginStatePhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'properties', WidgetPluginPropertiesPhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'methods', WidgetPluginMethodsPhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'events', WidgetPluginEventsPhaseMembers<Type, Interfaces>> : WidgetPluginStructureStage<Type, Interfaces, 'done', WidgetPluginDonePhase<Type, Interfaces>>;
|
|
412
529
|
/**
|
|
413
530
|
* `slots: never` is the canonical explicit-empty slots declaration (diagnostic #10 amendment
|
|
414
531
|
* "declaration-presence semantics and public `WidgetPlugin.capabilities`"): the phase still exists —
|
|
415
532
|
* gated on `HasWidgetCapability`, never on whether `WidgetCapabilityOf<Interfaces, 'slots'>` happens to
|
|
416
533
|
* be `never` — and completes as `.slots({})`, since `ExactWidgetSlotDefinitions` for zero slot names is
|
|
417
|
-
* exactly `{}`.
|
|
534
|
+
* exactly `{}`. A plugin-level structure validator is declared with the following `.structure()` phase.
|
|
418
535
|
*/
|
|
419
536
|
type WidgetPluginSlotsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'slots'> extends true ? WidgetPluginOrderedPhase<{
|
|
420
|
-
slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions
|
|
421
|
-
}, Interfaces, 'slots'> :
|
|
537
|
+
slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions) => WidgetPluginStructurePhase<Type, Interfaces>;
|
|
538
|
+
}, Interfaces, 'slots'> : WidgetPluginStructurePhase<Type, Interfaces>;
|
|
422
539
|
type WidgetPluginConfigPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'config'> extends true ? WidgetPluginOrderedPhase<{
|
|
423
540
|
config: (definition: WidgetConfigDefinition<Interfaces>) => WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
424
541
|
}, Interfaces, 'config'> : WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
@@ -431,8 +548,9 @@ interface WidgetPluginDescriptionPhase<Type extends string> {
|
|
|
431
548
|
/**
|
|
432
549
|
* Starts the plugin builder for one plugin `type`.
|
|
433
550
|
*
|
|
434
|
-
* Phase order is `description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
435
|
-
* a phase exists only when its capability is declared
|
|
551
|
+
* Phase order is `description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
552
|
+
* a capability phase exists only when its capability is declared, while the optional `structure` phase
|
|
553
|
+
* (the plugin-level structure validator) is available to every plugin. Calling a phase out of order (or
|
|
436
554
|
* repeating it) fails type-checking with an order-specific diagnostic; the runtime builder itself is
|
|
437
555
|
* order-agnostic.
|
|
438
556
|
*/
|
|
@@ -455,10 +573,11 @@ interface WidgetCatalog {
|
|
|
455
573
|
type WidgetSystemValidateStructureContext<Plugins extends AnyWidgetPluginTuple> = {
|
|
456
574
|
readonly blueprint: BlueprintCompileView<Plugins>;
|
|
457
575
|
} & DiagnosticCollector<RelativeSystemStructureDiagnosticInput<Plugins>>;
|
|
458
|
-
|
|
459
|
-
|
|
576
|
+
/** `Result` is the validator's own return type (see `WidgetSynchronousResult`). */
|
|
577
|
+
type WidgetSystemValidateStructure<Plugins extends AnyWidgetPluginTuple, Result = unknown> = (ctx: WidgetSystemValidateStructureContext<Plugins>) => WidgetSynchronousResult<Result>;
|
|
578
|
+
interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple, Result = unknown> {
|
|
460
579
|
readonly plugins: Plugins;
|
|
461
|
-
readonly validateStructure?: WidgetSystemValidateStructure<Plugins>;
|
|
580
|
+
readonly validateStructure?: WidgetSystemValidateStructure<Plugins, Result>;
|
|
462
581
|
}
|
|
463
582
|
/**
|
|
464
583
|
* Selects one registered plugin by its `type` discriminator.
|
|
@@ -466,6 +585,20 @@ interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple> {
|
|
|
466
585
|
type WidgetPluginOf<Plugins extends AnyWidgetPluginTuple, Type extends string> = Extract<Plugins[number], {
|
|
467
586
|
readonly type: Type;
|
|
468
587
|
}>;
|
|
588
|
+
/** The registered plugin types that are string literals; a plugin typed with a broad `string` adds none. */
|
|
589
|
+
type WidgetPluginLiteralTypeOf<Plugins extends AnyWidgetPluginTuple> = WidgetPluginTypeOf<Plugins[number]> extends (infer Type) ? Type extends string ? (string extends Type ? never : Type) : never : never;
|
|
590
|
+
/**
|
|
591
|
+
* `getPlugin` overloads. `Plugins` appears only in type-parameter constraints and in `WidgetPluginOf`, so
|
|
592
|
+
* a precisely typed System stays assignable to a loosely typed one (`WidgetSystem`).
|
|
593
|
+
*/
|
|
594
|
+
interface WidgetSystemGetPlugin<Plugins extends AnyWidgetPluginTuple> {
|
|
595
|
+
/** A registered literal type (or a union of them): that exact plugin. */
|
|
596
|
+
<Type extends WidgetPluginLiteralTypeOf<Plugins>>(type: Type): WidgetPluginOf<Plugins, Type>;
|
|
597
|
+
/** Any type on a loosely typed System (one with a broad `string` plugin type), which may be unregistered. */
|
|
598
|
+
<Type extends WidgetPluginTypeOf<Plugins[number]>>(type: Type): AnyWidgetPlugin | null;
|
|
599
|
+
/** A broad `string`, which may name no registered plugin. An unregistered literal on a precisely typed System stays a type error. */
|
|
600
|
+
<Type extends string>(type: string extends Type ? Type : never): AnyWidgetPlugin | null;
|
|
601
|
+
}
|
|
469
602
|
interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
470
603
|
/**
|
|
471
604
|
* The registered plugin tuple. It defines this instance's TypeScript universe; there is no
|
|
@@ -474,7 +607,8 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
|
|
|
474
607
|
readonly plugins: Plugins;
|
|
475
608
|
readonly validateStructure: WidgetSystemValidateStructure<Plugins> | null;
|
|
476
609
|
readonly catalog: WidgetCatalog;
|
|
477
|
-
|
|
610
|
+
/** The registered plugin of `type`, or `null` when no plugin of that type is registered. */
|
|
611
|
+
getPlugin: WidgetSystemGetPlugin<Plugins>;
|
|
478
612
|
/**
|
|
479
613
|
* The compilation boundary. The input is `unknown` because JSON-parsed/untrusted document data is
|
|
480
614
|
* the real boundary; malformed input still produces an inspectable Blueprint.
|
|
@@ -487,12 +621,27 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
|
|
|
487
621
|
* editing your own object.
|
|
488
622
|
*/
|
|
489
623
|
createBlueprint: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
|
|
624
|
+
/**
|
|
625
|
+
* Parses `text` with `JSON.parse` and compiles the result. Equivalent to
|
|
626
|
+
* `createBlueprint(JSON.parse(text))`, including its diagnostics: a value Core parsed itself can only
|
|
627
|
+
* leave the authored JSON domain through a non-finite number (`1e400` parses to `Infinity`, diagnosed as
|
|
628
|
+
* `json-incompatible-value` / `non-finite-number`) or through nesting deeper than `MAX_JSON_DEPTH`, so Core
|
|
629
|
+
* replaces the descriptor-level JSON-domain inspection with a cheaper scan for exactly those two cases and
|
|
630
|
+
* runs the full inspection when the scan finds either. `sourceJsonCompatible` is `true` only when that
|
|
631
|
+
* proof succeeds. Invalid JSON text throws the `SyntaxError` from `JSON.parse`, unchanged. The parsed
|
|
632
|
+
* source is referenced by nothing but the Blueprint.
|
|
633
|
+
*/
|
|
634
|
+
createBlueprintFromJson: (text: string) => WidgetSystemBlueprint<Plugins>;
|
|
490
635
|
}
|
|
491
|
-
type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-type';
|
|
636
|
+
type WidgetSystemConfigurationErrorCode = 'invalid-options' | 'foreign-plugin' | 'duplicate-plugin-type';
|
|
492
637
|
/**
|
|
493
|
-
* Thrown by `createWidgetSystem` for an invalid plugin registration. Discriminate by
|
|
494
|
-
* `message` is not protocol.
|
|
638
|
+
* Thrown by `createWidgetSystem` for invalid options or an invalid plugin registration. Discriminate by
|
|
639
|
+
* class and `code`; `message` is not protocol. The options shape is checked first, then the plugin
|
|
640
|
+
* entries in tuple order.
|
|
495
641
|
*
|
|
642
|
+
* - `invalid-options`: `options` is not an object, `options.plugins` is not an array, or
|
|
643
|
+
* `options.validateStructure` is present (neither `undefined` nor `null`) but not a function.
|
|
644
|
+
* `pluginIndex`, `pluginType` and `firstPluginIndex` are `null`.
|
|
496
645
|
* - `foreign-plugin`: the entry at `pluginIndex` was not completed by this loaded module instance
|
|
497
646
|
* (another module instance or a structural look-alike). `pluginType` is its `type` when a string,
|
|
498
647
|
* else `null`. `firstPluginIndex` is `null`.
|
|
@@ -501,19 +650,26 @@ type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-t
|
|
|
501
650
|
*/
|
|
502
651
|
declare class WidgetSystemConfigurationError extends Error {
|
|
503
652
|
readonly code: WidgetSystemConfigurationErrorCode;
|
|
504
|
-
readonly pluginIndex: number;
|
|
653
|
+
readonly pluginIndex: number | null;
|
|
505
654
|
readonly pluginType: string | null;
|
|
506
655
|
readonly firstPluginIndex: number | null;
|
|
507
656
|
readonly name = "WidgetSystemConfigurationError";
|
|
508
|
-
constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
|
|
657
|
+
constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number | null, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
|
|
509
658
|
}
|
|
510
659
|
/**
|
|
511
|
-
* Creates an instance-scoped, immutable widget system.
|
|
660
|
+
* Creates an instance-scoped, immutable widget system. Malformed options, foreign plugins and duplicate
|
|
661
|
+
* `plugin.type` are rejected with a `WidgetSystemConfigurationError`.
|
|
512
662
|
*/
|
|
513
|
-
declare function createWidgetSystem<const Plugins extends AnyWidgetPluginTuple>(options: CreateWidgetSystemOptions<Plugins>): WidgetSystem<Plugins>;
|
|
663
|
+
declare function createWidgetSystem<const Plugins extends AnyWidgetPluginTuple, Result = unknown>(options: CreateWidgetSystemOptions<Plugins, Result>): WidgetSystem<Plugins>;
|
|
514
664
|
//#endregion
|
|
515
665
|
//#region src/internal/contract.d.ts
|
|
516
666
|
type WidgetSystemBlueprintStatus = 'valid' | 'invalid';
|
|
667
|
+
/**
|
|
668
|
+
* The structured (array form) `SourcePath` of one Blueprint node's authored object within `blueprint.source`,
|
|
669
|
+
* e.g. `[]` for the root and `['slots', 'children', 0]` for its first child. Used verbatim as a `SourcePatch`
|
|
670
|
+
* path against the same source it addresses exactly that node.
|
|
671
|
+
*/
|
|
672
|
+
type BlueprintSourcePath = readonly (string | number)[];
|
|
517
673
|
interface BlueprintWidgetNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple, Source = unknown> {
|
|
518
674
|
/**
|
|
519
675
|
* The exact source fragment for this recovered node. Never mutated, cloned or frozen by the core.
|
|
@@ -527,6 +683,10 @@ interface BlueprintWidgetNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidg
|
|
|
527
683
|
*/
|
|
528
684
|
interface UnresolvedBlueprintWidgetNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple, Source = unknown> extends BlueprintWidgetNodeBase<Plugins, Source> {
|
|
529
685
|
readonly resolved: false;
|
|
686
|
+
/** Best-effort identity hint: the authored `id` when it is a string, else `null`. */
|
|
687
|
+
readonly id: string | null;
|
|
688
|
+
/** Best-effort identity hint: the authored `type` when it is a string (even an unknown one), else `null`. */
|
|
689
|
+
readonly type: string | null;
|
|
530
690
|
}
|
|
531
691
|
/**
|
|
532
692
|
* Complete declared semantic slot map. Only declared slots appear, every declared slot exists, and an
|
|
@@ -651,7 +811,7 @@ interface BlueprintCompileView<Plugins extends AnyWidgetPluginTuple = AnyWidgetP
|
|
|
651
811
|
/**
|
|
652
812
|
* Read-only valid-Blueprint view handed to runtime semantic callbacks (`compute`, `execute`).
|
|
653
813
|
*/
|
|
654
|
-
interface
|
|
814
|
+
interface BlueprintRuntimeView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
655
815
|
readonly root: ResolvedBlueprintWidgetNode<Plugins, JsonValue>;
|
|
656
816
|
getWidget: (id: WidgetId) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
657
817
|
getParent: (node: ResolvedBlueprintWidgetNode<Plugins>) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
@@ -666,6 +826,11 @@ interface ValidBlueprintView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPlu
|
|
|
666
826
|
type WidgetSourceFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetPluginTuple> = {
|
|
667
827
|
readonly id: WidgetId;
|
|
668
828
|
readonly type: WidgetPluginTypeOf<Plugin>;
|
|
829
|
+
/**
|
|
830
|
+
* The reserved extension key: any JSON value, preserved in `source` and never interpreted by
|
|
831
|
+
* Core. Every other unrecognized own key is diagnosed as `unexpected-widget-field`.
|
|
832
|
+
*/
|
|
833
|
+
readonly meta?: JsonValue;
|
|
669
834
|
} & (HasWidgetCapability<WidgetInterfacesOf<Plugin>, 'config'> extends true ? [null] extends [WidgetRawConfigOf<WidgetInterfacesOf<Plugin>>] ? {
|
|
670
835
|
readonly config?: WidgetRawConfigOf<WidgetInterfacesOf<Plugin>>;
|
|
671
836
|
} : {
|
|
@@ -689,13 +854,14 @@ interface WidgetSystemBlueprintBase<Plugins extends AnyWidgetPluginTuple, Source
|
|
|
689
854
|
*/
|
|
690
855
|
recompile: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
|
|
691
856
|
}
|
|
692
|
-
interface ValidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends WidgetSystemBlueprintBase<Plugins,
|
|
857
|
+
interface ValidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends WidgetSystemBlueprintBase<Plugins, WidgetSource<Plugins>> {
|
|
693
858
|
readonly status: 'valid';
|
|
694
859
|
readonly sourceJsonCompatible: true;
|
|
695
860
|
readonly root: ResolvedBlueprintWidgetNode<Plugins, JsonValue>;
|
|
696
861
|
getWidget: (id: WidgetId) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
697
862
|
getParent: (node: BlueprintWidgetNode<Plugins>) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
698
863
|
getLocation: (node: BlueprintWidgetNode<Plugins>) => WidgetLocation<Plugins, JsonValue> | null;
|
|
864
|
+
getSourcePath: (node: BlueprintWidgetNode<Plugins>) => BlueprintSourcePath | null;
|
|
699
865
|
getChildren: (node: BlueprintWidgetNode<Plugins>) => readonly ResolvedBlueprintWidgetNode<Plugins, JsonValue>[];
|
|
700
866
|
getChildrenAt: (node: BlueprintWidgetNode<Plugins>, slot: WidgetMemberKey) => readonly ResolvedBlueprintWidgetNode<Plugins, JsonValue>[];
|
|
701
867
|
readonly diagnostics: readonly never[];
|
|
@@ -708,6 +874,7 @@ interface InvalidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = An
|
|
|
708
874
|
getWidget: (id: WidgetId) => BlueprintWidgetNode<Plugins, Source> | null;
|
|
709
875
|
getParent: (node: BlueprintWidgetNode<Plugins>) => BlueprintWidgetNode<Plugins, Source> | null;
|
|
710
876
|
getLocation: (node: BlueprintWidgetNode<Plugins>) => WidgetLocation<Plugins, Source> | null;
|
|
877
|
+
getSourcePath: (node: BlueprintWidgetNode<Plugins>) => BlueprintSourcePath | null;
|
|
711
878
|
getChildren: (node: BlueprintWidgetNode<Plugins>) => readonly BlueprintWidgetNode<Plugins, Source>[];
|
|
712
879
|
getChildrenAt: (node: BlueprintWidgetNode<Plugins>, slot: WidgetMemberKey) => readonly BlueprintWidgetNode<Plugins, Source>[];
|
|
713
880
|
readonly diagnostics: readonly BlueprintDiagnostic<Plugins>[];
|
|
@@ -733,14 +900,16 @@ interface RuntimeState<T> {
|
|
|
733
900
|
getDiagnostics: () => readonly RuntimeStateDiagnostic[];
|
|
734
901
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeStateDiagnostic[]) => void) => () => void;
|
|
735
902
|
}
|
|
903
|
+
/** A completed result's ok value is exactly what `compute` returned (never an added `null`). */
|
|
736
904
|
interface RuntimeProperty<T> {
|
|
737
|
-
get: () => ExecutionResult<T
|
|
738
|
-
subscribe: (listener: (result: ExecutionResult<T
|
|
905
|
+
get: () => ExecutionResult<T, RuntimePropertyDiagnostic>;
|
|
906
|
+
subscribe: (listener: (result: ExecutionResult<T, RuntimePropertyDiagnostic>) => void) => () => void;
|
|
739
907
|
getDiagnostics: () => readonly RuntimePropertyDiagnostic[];
|
|
740
908
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimePropertyDiagnostic[]) => void) => () => void;
|
|
741
909
|
}
|
|
910
|
+
/** A successful invocation's ok value is exactly what `execute` returned (never an added `null`). */
|
|
742
911
|
interface RuntimeMethod<Fn extends (...args: any[]) => any> {
|
|
743
|
-
(...args: Parameters<Fn>): ExecutionResult<ReturnType<Fn
|
|
912
|
+
(...args: Parameters<Fn>): ExecutionResult<ReturnType<Fn>, RuntimeMethodDiagnostic>;
|
|
744
913
|
getDiagnostics: () => readonly RuntimeMethodDiagnostic[];
|
|
745
914
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeMethodDiagnostic[]) => void) => () => void;
|
|
746
915
|
}
|
|
@@ -749,6 +918,12 @@ interface RuntimeEvent<Args extends readonly unknown[]> {
|
|
|
749
918
|
}
|
|
750
919
|
type RuntimeStateSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? {
|
|
751
920
|
readonly state: { readonly [Key in WidgetStateKeyOf<Interfaces>]: RuntimeState<WidgetStateValueOf<Interfaces, Key>>; };
|
|
921
|
+
/**
|
|
922
|
+
* `WidgetSystemRuntime.resetState()` scoped to this widget: restores its State members to their
|
|
923
|
+
* initialization outcome without running `validate`, in one batch; Property/Method diagnostic
|
|
924
|
+
* snapshots are not reset. Throws `WidgetSystemRuntimeDisposedError` after dispose.
|
|
925
|
+
*/
|
|
926
|
+
resetState: () => void;
|
|
752
927
|
} : unknown;
|
|
753
928
|
type RuntimePropertySurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? {
|
|
754
929
|
readonly properties: { readonly [Name in WidgetPropertyKeyOf<Interfaces>]: RuntimeProperty<WidgetPropertyValueOf<Interfaces, Name>>; };
|
|
@@ -770,7 +945,7 @@ type RuntimeMethodSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapabi
|
|
|
770
945
|
type RuntimeWidgetFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = {
|
|
771
946
|
readonly id: WidgetId;
|
|
772
947
|
readonly type: WidgetPluginTypeOf<Plugin>;
|
|
773
|
-
readonly
|
|
948
|
+
readonly blueprintNode: ResolvedBlueprintWidgetNodeFor<Plugin, Plugins>;
|
|
774
949
|
/**
|
|
775
950
|
* This widget's own aggregate diagnostic snapshot: state members -> property members -> method
|
|
776
951
|
* members, declaration order within each capability, each primitive's own local diagnostic order.
|
|
@@ -785,18 +960,50 @@ type RuntimeWidget<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple>
|
|
|
785
960
|
* Executable instance of a valid Blueprint.
|
|
786
961
|
*
|
|
787
962
|
* After `dispose()`, `isDisposed` and `blueprint` stay readable while every live query/operation and
|
|
788
|
-
* every new subscription throws `WidgetSystemRuntimeDisposedError`.
|
|
963
|
+
* every new subscription throws `WidgetSystemRuntimeDisposedError`. Disposal notifies only the listeners
|
|
964
|
+
* registered with `subscribeDisposal()`; it emits no State, Property, Event or diagnostic notification.
|
|
789
965
|
*/
|
|
790
966
|
interface WidgetSystemRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
791
967
|
readonly blueprint: ValidWidgetSystemBlueprint<Plugins>;
|
|
792
968
|
readonly isDisposed: boolean;
|
|
793
969
|
getWidget: (id: WidgetId) => RuntimeWidget<Plugins> | null;
|
|
970
|
+
/**
|
|
971
|
+
* Restores every State member of every widget to its initialization outcome (override > default >
|
|
972
|
+
* `null`, as validated when this Runtime was created): the same value and the same diagnostic snapshot,
|
|
973
|
+
* without running `validate` again. All writes form one batch, so dependents recompute and subscribers
|
|
974
|
+
* are notified once. Property and Method diagnostic snapshots are not reset; Properties re-evaluate
|
|
975
|
+
* through ordinary invalidation.
|
|
976
|
+
*/
|
|
977
|
+
resetState: () => void;
|
|
978
|
+
/**
|
|
979
|
+
* The current value of every State member, keyed by widget id and then member key, in exactly the
|
|
980
|
+
* shape `overrideStateDefaults` accepts: `blueprint.createRuntime({ overrideStateDefaults:
|
|
981
|
+
* runtime.snapshotState() })` reproduces every non-null value. Members whose value is `null` are
|
|
982
|
+
* omitted, and so are widgets left with no entry. Returns a fresh plain object owned by the caller;
|
|
983
|
+
* the values themselves are passed by reference, not cloned.
|
|
984
|
+
*/
|
|
985
|
+
snapshotState: () => Record<WidgetId, Record<WidgetMemberKey, unknown>>;
|
|
794
986
|
/**
|
|
795
987
|
* Runtime-level diagnostics plus the current state/property/method diagnostic snapshots, in deterministic
|
|
796
988
|
* order. Never history, and never activates property evaluation.
|
|
797
989
|
*/
|
|
798
|
-
getDiagnostics: () => readonly
|
|
799
|
-
subscribeDiagnostics: (listener: (diagnostics: readonly
|
|
990
|
+
getDiagnostics: () => readonly RuntimeDiagnostic[];
|
|
991
|
+
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeDiagnostic[]) => void) => () => void;
|
|
992
|
+
/**
|
|
993
|
+
* Registers a listener that runs exactly once, synchronously, inside the first `dispose()` call, with no
|
|
994
|
+
* arguments — for a host to cancel the asynchronous work it owns. By then the Runtime is already fully
|
|
995
|
+
* disposed: `isDisposed` is `true`, every Runtime-owned subscription is torn down, a live operation throws
|
|
996
|
+
* `WidgetSystemRuntimeDisposedError`, `dispose()` is a no-op, and `blueprint` and a widget's `id`,
|
|
997
|
+
* `type` and `blueprintNode` stay readable. Listeners run in subscription order, like Event listeners from
|
|
998
|
+
* a list fixed when delivery starts: one removed meanwhile still runs, and none can be added meanwhile,
|
|
999
|
+
* because subscribing to a disposed Runtime throws `WidgetSystemRuntimeDisposedError`, as it does after
|
|
1000
|
+
* disposal in general (the listener is never invoked immediately). A throwing listener never reaches the
|
|
1001
|
+
* `dispose()` caller or stops the remaining listeners; it is reported asynchronously like any other
|
|
1002
|
+
* isolated listener exception. Registering the same function twice makes two independent registrations.
|
|
1003
|
+
* The returned unsubscribe function is idempotent and safe to call before or after disposal; once the
|
|
1004
|
+
* listener has run it does nothing, and the Runtime keeps no reference to the listener.
|
|
1005
|
+
*/
|
|
1006
|
+
subscribeDisposal: (listener: () => void) => () => void;
|
|
800
1007
|
dispose: () => void;
|
|
801
1008
|
}
|
|
802
1009
|
//#endregion
|
|
@@ -807,14 +1014,23 @@ interface DiagnosticBase<Code extends string = string, Location = unknown> {
|
|
|
807
1014
|
readonly location: Location;
|
|
808
1015
|
readonly message: string;
|
|
809
1016
|
}
|
|
810
|
-
/** General structural diagnostic shape for code which does not need a narrower union. */
|
|
811
|
-
type Diagnostic<Code extends string = string, Location = unknown> = DiagnosticBase<Code, Location>;
|
|
812
1017
|
declare const EMPTY_DIAGNOSTICS: readonly never[];
|
|
813
1018
|
declare class WidgetSystemRuntimeDisposedError extends Error {
|
|
814
1019
|
readonly name = "WidgetSystemRuntimeDisposedError";
|
|
815
1020
|
readonly code: "runtime-disposed";
|
|
816
1021
|
constructor(message?: string);
|
|
817
1022
|
}
|
|
1023
|
+
/**
|
|
1024
|
+
* Thrown when one Runtime's event emits nest deeper than its re-entrancy limit: an event listener keeps
|
|
1025
|
+
* re-invoking a Method that emits again. A non-semantic safety guard against runaway re-entrancy (a
|
|
1026
|
+
* `RangeError`, like any other runaway recursion), never a Diagnostic. Event-listener isolation does not
|
|
1027
|
+
* swallow it, so it unwinds every nested emit to the operation that started the loop.
|
|
1028
|
+
*/
|
|
1029
|
+
declare class WidgetSystemRuntimeReentrancyError extends RangeError {
|
|
1030
|
+
readonly name = "WidgetSystemRuntimeReentrancyError";
|
|
1031
|
+
readonly code: "emit-depth-exceeded";
|
|
1032
|
+
constructor(message?: string);
|
|
1033
|
+
}
|
|
818
1034
|
interface RelativeValueDiagnosticInput {
|
|
819
1035
|
readonly message: string;
|
|
820
1036
|
readonly path?: DiagnosticPath;
|
|
@@ -925,7 +1141,9 @@ type BlueprintDependencyOperation = BlueprintDependencyReference['operation'];
|
|
|
925
1141
|
type BlueprintDiagnosticRelated<Plugins extends AnyWidgetPluginTuple> = NonEmptyReadonlyArray<BlueprintNodeDiagnosticLocation<Plugins>>;
|
|
926
1142
|
type BlueprintDefinitionDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = DiagnosticBase<'invalid-widget-definition', BlueprintWidgetDiagnosticLocation<Plugins>> | (DiagnosticBase<'invalid-widget-id', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
927
1143
|
readonly path: DiagnosticPath;
|
|
928
|
-
|
|
1144
|
+
}) | (DiagnosticBase<'duplicate-widget-id', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
1145
|
+
readonly path: DiagnosticPath;
|
|
1146
|
+
readonly related: BlueprintDiagnosticRelated<Plugins>;
|
|
929
1147
|
}) | (DiagnosticBase<'invalid-widget-type', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
930
1148
|
readonly path: DiagnosticPath;
|
|
931
1149
|
}) | (DiagnosticBase<'unknown-widget-type', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
@@ -940,6 +1158,8 @@ type BlueprintDefinitionDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWid
|
|
|
940
1158
|
readonly path: DiagnosticPath;
|
|
941
1159
|
}) | (DiagnosticBase<'invalid-widget-slot', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
942
1160
|
readonly path: DiagnosticPath;
|
|
1161
|
+
}) | (DiagnosticBase<'unexpected-widget-field', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
1162
|
+
readonly path: DiagnosticPath;
|
|
943
1163
|
});
|
|
944
1164
|
type BlueprintConfigDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = DiagnosticBase<'invalid-widget-config', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
945
1165
|
readonly path?: DiagnosticPath;
|
|
@@ -955,13 +1175,14 @@ type BlueprintDependencyDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWid
|
|
|
955
1175
|
}) | (DiagnosticBase<'ambiguous-dependency-target', BlueprintDependencyDiagnosticLocation<Plugins>> & {
|
|
956
1176
|
readonly dependency: BlueprintDependencyReference;
|
|
957
1177
|
readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
|
|
958
|
-
}) | (DiagnosticBase<'property-dependency-has-
|
|
1178
|
+
}) | (DiagnosticBase<'property-dependency-has-side-effects', BlueprintDependencyDiagnosticLocation<Plugins>> & {
|
|
959
1179
|
readonly dependency: BlueprintDependencyReference;
|
|
960
1180
|
readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
|
|
961
1181
|
}) | (DiagnosticBase<'property-evaluation-cycle', BlueprintDependencyDiagnosticLocation<Plugins>> & {
|
|
962
|
-
|
|
1182
|
+
/** Every member of the cycle, the subject included, in member order; one array shared by all diagnostics of the cycle. */
|
|
1183
|
+
readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
|
|
963
1184
|
});
|
|
964
|
-
type JsonCompatibilityReason = 'undefined' | 'non-finite-number' | 'bigint' | 'symbol' | 'function' | 'unsupported-object-prototype' | 'symbol-key' | 'accessor-property' | 'sparse-array' | 'array-extra-property' | 'cyclic-reference';
|
|
1185
|
+
type JsonCompatibilityReason = 'undefined' | 'non-finite-number' | 'bigint' | 'symbol' | 'function' | 'unsupported-object-prototype' | 'symbol-key' | 'accessor-property' | 'sparse-array' | 'array-extra-property' | 'cyclic-reference' | 'max-depth-exceeded';
|
|
965
1186
|
type JsonCompatibilityDiagnostic = DiagnosticBase<'json-incompatible-value', BlueprintSourceDiagnosticLocation> & {
|
|
966
1187
|
readonly path: DiagnosticPath;
|
|
967
1188
|
readonly reason: JsonCompatibilityReason;
|
|
@@ -988,7 +1209,7 @@ type RuntimePrimitiveDiagnosticLocation = {
|
|
|
988
1209
|
interface RuntimeLevelDiagnosticLocation {
|
|
989
1210
|
readonly type: 'runtime';
|
|
990
1211
|
}
|
|
991
|
-
type RuntimeDiagnosticLocation = RuntimePrimitiveDiagnosticLocation;
|
|
1212
|
+
type RuntimeDiagnosticLocation = RuntimePrimitiveDiagnosticLocation | RuntimeLevelDiagnosticLocation;
|
|
992
1213
|
type RuntimeStateDiagnostic = DiagnosticBase<'invalid-state-value', Extract<RuntimePrimitiveDiagnosticLocation, {
|
|
993
1214
|
type: 'state';
|
|
994
1215
|
}>> & {
|
|
@@ -1020,7 +1241,7 @@ type RuntimeMethodResultDiagnostic = DiagnosticBase<'invalid-method-result', Ext
|
|
|
1020
1241
|
type RuntimeDependencyTargetFailedDiagnostic = DiagnosticBase<'dependency-target-failed', RuntimePrimitiveDiagnosticLocation> & {
|
|
1021
1242
|
readonly dependency: BlueprintDependencyReference;
|
|
1022
1243
|
readonly related: NonEmptyReadonlyArray<RuntimePrimitiveDiagnosticLocation>;
|
|
1023
|
-
readonly cause:
|
|
1244
|
+
readonly cause: RuntimeWidgetDiagnostic;
|
|
1024
1245
|
};
|
|
1025
1246
|
type RuntimeDependencyValueRejectedDiagnostic = DiagnosticBase<'dependency-value-rejected', RuntimePrimitiveDiagnosticLocation> & {
|
|
1026
1247
|
readonly dependency: BlueprintDependencyReference;
|
|
@@ -1039,7 +1260,6 @@ type RuntimeMethodDependencyDiagnostic = (RuntimeDependencyTargetFailedDiagnosti
|
|
|
1039
1260
|
};
|
|
1040
1261
|
type RuntimePropertyDiagnostic = RuntimePropertyResultDiagnostic | RuntimePropertyDependencyDiagnostic;
|
|
1041
1262
|
type RuntimeMethodDiagnostic = RuntimeMethodArgsDiagnostic | RuntimeMethodResultDiagnostic | RuntimeMethodDependencyDiagnostic;
|
|
1042
|
-
type RuntimeDiagnostic = RuntimeStateDiagnostic | RuntimePropertyDiagnostic | RuntimeMethodDiagnostic;
|
|
1043
1263
|
type RuntimeLevelDiagnostic = (DiagnosticBase<'invalid-state-overrides', RuntimeLevelDiagnosticLocation> & {
|
|
1044
1264
|
readonly path?: DiagnosticPath;
|
|
1045
1265
|
readonly reason?: string;
|
|
@@ -1057,7 +1277,7 @@ type RuntimeLevelDiagnostic = (DiagnosticBase<'invalid-state-overrides', Runtime
|
|
|
1057
1277
|
readonly reason?: string;
|
|
1058
1278
|
});
|
|
1059
1279
|
type RuntimeWidgetDiagnostic = RuntimeStateDiagnostic | RuntimePropertyDiagnostic | RuntimeMethodDiagnostic;
|
|
1060
|
-
type
|
|
1280
|
+
type RuntimeDiagnostic = RuntimeLevelDiagnostic | RuntimeWidgetDiagnostic;
|
|
1061
1281
|
//#endregion
|
|
1062
1282
|
//#region src/dep.d.ts
|
|
1063
1283
|
/**
|
|
@@ -1211,11 +1431,16 @@ type SelfStateDependencyOperations<Interfaces extends WidgetInterfaces, Consumer
|
|
|
1211
1431
|
} & (Consumer extends 'method' ? {
|
|
1212
1432
|
set: <Key extends WidgetStateKeyOf<Interfaces>>(key: Key) => StateSetDepExpression<WidgetStateValueOf<Interfaces, Key>, false>;
|
|
1213
1433
|
} : unknown);
|
|
1434
|
+
/**
|
|
1435
|
+
* A self Property read yields exactly what its `compute` returned: a self target is never absent, so no
|
|
1436
|
+
* `null` is added (unlike a State read, whose member may hold `null`).
|
|
1437
|
+
*/
|
|
1214
1438
|
interface SelfPropertyDependencyOperations<Interfaces extends WidgetInterfaces> {
|
|
1215
|
-
get: <Name extends WidgetPropertyKeyOf<Interfaces>>(name: Name) => PropertyGetDepExpression<WidgetPropertyValueOf<Interfaces, Name
|
|
1439
|
+
get: <Name extends WidgetPropertyKeyOf<Interfaces>>(name: Name) => PropertyGetDepExpression<WidgetPropertyValueOf<Interfaces, Name>, false>;
|
|
1216
1440
|
}
|
|
1441
|
+
/** A self Method invocation yields exactly what its `execute` returned; see {@link SelfPropertyDependencyOperations}. */
|
|
1217
1442
|
interface SelfMethodDependencyOperations<Interfaces extends WidgetInterfaces> {
|
|
1218
|
-
invoke: <Name extends WidgetMethodKeyOf<Interfaces>>(name: Name) => MethodInvokeDepExpression<WidgetMethodArgsOf<Interfaces, Name>, WidgetMethodReturnOf<Interfaces, Name
|
|
1443
|
+
invoke: <Name extends WidgetMethodKeyOf<Interfaces>>(name: Name) => MethodInvokeDepExpression<WidgetMethodArgsOf<Interfaces, Name>, WidgetMethodReturnOf<Interfaces, Name>, false>;
|
|
1219
1444
|
}
|
|
1220
1445
|
/**
|
|
1221
1446
|
* `self` target stage: guaranteed target, strongly typed, and capability-aware.
|
|
@@ -1244,4 +1469,4 @@ interface DependencyBuilder<Interfaces extends WidgetInterfaces, Consumer extend
|
|
|
1244
1469
|
widget: (widgetId: WidgetId) => OptionalizableDependencyTarget<Consumer>;
|
|
1245
1470
|
}
|
|
1246
1471
|
//#endregion
|
|
1247
|
-
export {
|
|
1472
|
+
export { RuntimeDiagnostic as $, WidgetStateValidateContext as $n, WidgetCatalog as $t, BlueprintNodeDiagnostic as A, WidgetPluginDonePhase as An, WidgetStateValueOf as Ar, ResolvedBlueprintWidgetNodeViewFor as At, DiagnosticBase as B, WidgetPluginValidateStructure as Bn, RuntimeWidgetFor as Bt, BlueprintDependencyDiagnosticLocation as C, WidgetMethodValidateArgsContext as Cn, WidgetPropertyKeyOf as Cr, BlueprintWidgetNodeBase as Ct, BlueprintDiagnostic as D, WidgetPluginConfigMetadata as Dn, WidgetSlotNameOf as Dr, ResolvedBlueprintWidgetNode as Dt, BlueprintDependencyTarget as E, WidgetPluginCapabilities as En, WidgetResolvedConfigOf as Er, InvalidWidgetSystemBlueprint as Et, BlueprintSourceDiagnostic as F, WidgetPluginPropertiesPhase as Fn, MAX_JSON_DEPTH as Fr, RuntimeProperty as Ft, JsonCompatibilityReason as G, WidgetRegisterDepsContext as Gn, WidgetLocation as Gt, DiagnosticPath as H, WidgetPropertiesSection as Hn, SelfBlueprintWidgetNodeView as Ht, BlueprintSourceDiagnosticLocation as I, WidgetPluginSlotsPhase as In, isJsonValue as Ir, RuntimePropertySurface as It, RelativeStructureDiagnosticLocation as J, WidgetSlotDefinitions as Jn, WidgetSourceFor as Jt, RelativePluginStructureDiagnosticInput as K, WidgetResolvedConfigContext as Kn, WidgetLocationView as Kt, BlueprintStructureDiagnostic as L, WidgetPluginStatePhase as Ln, RuntimeState as Lt, BlueprintPropertyDiagnosticLocation as M, WidgetPluginInterfacesPhase as Mn, JsonObject as Mr, RuntimeEventSurface as Mt, BlueprintSlotChildDiagnosticLocation as N, WidgetPluginMethodsPhase as Nn, JsonPrimitive as Nr, RuntimeMethod as Nt, BlueprintDiagnosticLocation as O, WidgetPluginConfigPhase as On, WidgetStateKeyOf as Or, ResolvedBlueprintWidgetNodeFor as Ot, BlueprintSlotDiagnosticLocation as P, WidgetPluginPhaseOrderViolation as Pn, JsonValue as Pr, RuntimeMethodSurface as Pt, RuntimeDependencyValueRejectedDiagnostic as Q, WidgetStateSection as Qn, CreateWidgetSystemOptions as Qt, BlueprintStructureDiagnosticLocation as R, WidgetPluginStructurePhase as Rn, RuntimeStateSurface as Rt, BlueprintDependencyDiagnostic as S, WidgetMethodExecuteContext as Sn, WidgetPropertiesOf as Sr, BlueprintWidgetNode as St, BlueprintDependencyReference as T, WidgetPlugin as Tn, WidgetRawConfigOf as Tr, CreateWidgetSystemRuntimeOptions as Tt, EMPTY_DIAGNOSTICS as U, WidgetPropertyComputeContext as Un, UnresolvedBlueprintWidgetNode as Ut, DiagnosticCollector as V, WidgetPluginValidateStructureContext as Vn, SelfBlueprintWidgetNode as Vt, JsonCompatibilityDiagnostic as W, WidgetPropertyDefinition as Wn, ValidWidgetSystemBlueprint as Wt, RelativeValueDiagnosticInput as X, WidgetStateDefaultContext as Xn, WidgetSystemBlueprintStatus as Xt, RelativeSystemStructureDiagnosticInput as Y, WidgetSlotValidateStructureContext as Yn, WidgetSystemBlueprint as Yt, RuntimeDependencyTargetFailedDiagnostic as Z, WidgetStateMemberDefinition as Zn, WidgetSystemRuntime as Zt, ToExecutedDeps as _, WidgetEventsSection as _n, WidgetMethodArgsOf as _r, BlueprintNodeConfigFields as _t, MaybeOptional as a, WidgetSystemValidateStructure as an, HasWidgetCapability as ar, RuntimeMethodDiagnostic as at, BlueprintConfigDiagnostic as b, WidgetMethodDefinition as bn, WidgetMethodReturnOf as br, BlueprintSemanticSlotsView as bt, PropertyGetDepExpression as c, AnyWidgetPlugin as cn, WidgetEventArgsOf as cr, RuntimePropertyDependencyDiagnostic as ct, SelfMethodDependencyOperations as d, WidgetConfigDefinition as dn, WidgetId as dr, RuntimeStateDiagnostic as dt, WidgetCatalogEntry as en, WidgetValueContract as er, RuntimeDiagnosticLocation as et, SelfPropertyDependencyOperations as f, WidgetConfigJsonSchema as fn, WidgetInterfaces as fr, RuntimeWidgetDiagnostic as ft, ToExecutedDep as g, WidgetEventEmitterContext as gn, WidgetMemberValueOf as gr, BlueprintCompileView as gt, StateSetDepExpression as h, WidgetEventEmitter as hn, WidgetMemberKeysOf as hr, WidgetSystemRuntimeReentrancyError as ht, EmptyRegisteredDeps as i, WidgetSystemConfigurationErrorCode as in, ExecutionResult as ir, RuntimeMethodDependencyDiagnostic as it, BlueprintNodeDiagnosticLocation as j, WidgetPluginEventsPhase as jn, JsonArray as jr, RuntimeEvent as jt, BlueprintMethodDiagnosticLocation as k, WidgetPluginDescriptionPhase as kn, WidgetStateOf as kr, ResolvedBlueprintWidgetNodeView as kt, RegisteredDeps as l, AnyWidgetPluginTuple as ln, WidgetEventKeyOf as lr, RuntimePropertyDiagnostic as lt, StateGetDepExpression as m, WidgetEventDefinition as mn, WidgetMemberKey as mr, WidgetSystemRuntimeDisposedError as mt, DependencyBuilder as n, WidgetSystem as nn, createWidgetValueContract as nr, RuntimeLevelDiagnosticLocation as nt, MethodInvokeDepExpression as o, WidgetSystemValidateStructureContext as on, NonEmptyReadonlyArray as or, RuntimeMethodResultDiagnostic as ot, SelfStateDependencyOperations as p, WidgetConfigValidateContext as pn, WidgetInterfacesViolationOf as pr, SourceAccessDiagnostic as pt, RelativeSlotStructureDiagnosticInput as q, WidgetSlotDefinition as qn, WidgetSource as qt, DependencyConsumer as r, WidgetSystemConfigurationError as rn, ExecutionFailure as rr, RuntimeMethodArgsDiagnostic as rt, OptionalizableDependencyTarget as s, createWidgetSystem as sn, WidgetCapabilityOf as sr, RuntimePrimitiveDiagnosticLocation as st, AnyDepExpression as t, WidgetPluginOf as tn, createWidgetPlugin as tr, RuntimeLevelDiagnostic as tt, SelfDependencyTarget as u, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as un, WidgetEventsOf as ur, RuntimePropertyResultDiagnostic as ut, UnknownTargetDependencyOperations as v, WidgetInterfacesOf as vn, WidgetMethodKeyOf as vr, BlueprintRuntimeView as vt, BlueprintDependencyOperation as w, WidgetMethodsSection as wn, WidgetPropertyValueOf as wr, BlueprintWidgetNodeView as wt, BlueprintDefinitionDiagnostic as x, WidgetMethodEventEmitter as xn, WidgetMethodsOf as xr, BlueprintSourcePath as xt, UnknownTargetStateDependencyOperations as y, WidgetInterfacesViolation as yn, WidgetMethodOf as yr, BlueprintSemanticSlots as yt, BlueprintWidgetDiagnosticLocation as z, WidgetPluginTypeOf as zn, RuntimeWidget as zt };
|