graphddb 0.3.1 → 0.4.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 +1 -1
- package/dist/{chunk-YIXXTGZ6.js → chunk-72VZYOSG.js} +191 -239
- package/dist/{chunk-PNIZS37E.js → chunk-GWFZVNAV.js} +8 -118
- package/dist/{chunk-VST3WOK3.js → chunk-PC54CW5P.js} +3 -5
- package/dist/cli.js +2 -2
- package/dist/index.d.ts +298 -104
- package/dist/index.js +279 -37
- package/dist/testing/index.d.ts +1 -1
- package/dist/testing/index.js +2 -2
- package/dist/{types-DuJ08bgc.d.ts → types-CpCo8yHP.d.ts} +140 -419
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as EntityMetadata, K as KeyDefinition, G as GsiDefinition, F as FieldOptions,
|
|
2
|
-
export {
|
|
1
|
+
import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as EntityMetadata, K as KeyDefinition, G as GsiDefinition, q as ModelKind, F as FieldOptions, r as DynamoType, s as ProjectionTransform, t as MaintainEvent, u as MembershipPredicate, v as MaintainConsistency, w as MaintainUpdateMode, x as MembershipPredicateOp, y as RelationOptions, A as AggregateOptions, z as AggregateValue, H as SelectBuilderSpec, J as RawCondition, L as TransactionSpec, N as Manifest, O as RetryOverride, Q as ExecutionPlan, V as FieldMetadata, X as ResolvedKey, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, Y as CdcEmulatorOptions, Z as ChangeHandler, _ as Unsubscribe, $ as FaultSpec, a0 as ConcurrentRecomputeRef, C as ChangeEvent, a1 as EventLog, a2 as ReplayOptions, a3 as ShardId, a4 as ViewDefinition, a5 as RelationMetadata, a6 as TransactionItemSpec, a7 as MaintainEffect, M as ModelStatic, f as DDBModel, a8 as Param, a9 as ParamDescriptor, aa as DefinitionMap, ab as OperationDefinition, ac as WriteDefinitionOptions, ad as PartialQueryKeyOf, ae as StrictSelectSpec, af as EntityInput, ag as UniqueQueryKeyOf, ah as EntityRef, ai as ConditionInput, aj as QueryModelContract, ak as QueryMethodSpec, al as CommandModelContract, am as CommandMethodSpec, an as ContractSpec, ao as QuerySpec, ap as CommandSpec, aq as ContextSpec, ar as OperationsDocument, as as AnyOperationDefinition, at as BridgeBundle, au as ConditionSpec } from './types-CpCo8yHP.js';
|
|
2
|
+
export { av as AggregateMetadata, aw as BatchDeleteRequest, ax as BatchGetOptions, ay as BatchGetRequest, az as BatchGetResult, aA as BatchPutRequest, aB as BatchResult, aC as BatchWriteRequest, aD as CONTRACT_RANGE_FANOUT_CONCURRENCY, aE as CdcMode, aF as Change, aG as ChangeBatch, aH as ChangeEventName, aI as ClockMode, aJ as CollectionEffect, aK as CollectionOptions, aL as Column, aM as ColumnMap, aN as CommandContractMethodSpec, aO as CommandInputShape, aP as CommandMethod, aQ as CommandPlan, aR as CommandResolutionTarget, aS as CommandResultKind, aT as CommandSelectShape, aU as CompiledFragment, aV as ComposeSpec, aW as CondSlot, aX as ConditionCheckInput, aY as Connection, aZ as ContractCallSignature, a_ as ContractCardinality, a$ as ContractCommandParams, b0 as ContractCommandResult, b1 as ContractComposeNode, b2 as ContractFromRef, b3 as ContractInputArity, b4 as ContractItem, b5 as ContractKeyFieldRef, b6 as ContractKeyInput, b7 as ContractKeyRef, b8 as ContractKeySpec, b9 as ContractKind, ba as ContractMethodOp, bb as ContractParamRef, bc as ContractQueryParams, bd as ContractResolution, be as CounterAggregate, bf as CounterEffect, bg as CtxBase, bh as DEFAULT_MAX_ATTEMPTS, bi as DEFAULT_RETRY_POLICY, bj as DeleteOptions, bk as DeriveEffect, bl as DerivedEdgeWrite, bm as DerivedUpdate, bn as DescriptorBinding, bo as ENTITY_WRITES_MARKER, bp as EdgeEffect, bq as EffectPath, br as EmbeddedMetadata, bs as EmitEffect, bt as EntityWritesDefinition, bu as EntityWritesShape, bv as ExecutableCommandContract, bw as ExecutableQueryContract, bx as FilterInput, by as FilterSpec, bz as FragmentInput, bA as GsiDefinitionMarker, bB as GsiOptions, bC as IdempotencyEffect, bD as InProcessWriteDescriptor, bE as InputArity, bF as KeyDefinitionMarker, bG as KeySegment, bH as KeySlot, bI as KeyStructure, bJ as KeyedResult, bK as LIFECYCLE_CONTRACT_MARKER, bL as LifecycleContract, bM as LifecycleEffects, bN as LiteralParam, bO as MaintainItem, bP as MaintainTrigger, bQ as MaintenanceGraph, bR as ManifestEntity, bS as ManifestField, bT as ManifestFieldType, bU as ManifestGsi, bV as ManifestKey, bW as ManifestRelation, bX as ManifestTable, bY as MembershipEffect, bZ as ModelRef, b_ as MutateMode, b$ as MutateOptions, c0 as MutateParallelResult, c1 as MutateTransactionResult, c2 as MutationBody, c3 as MutationDescriptorMap, c4 as MutationFragment, c5 as MutationInputProxy, c6 as MutationInputRef, c7 as MutationIntent, c8 as NumberParam, c9 as OperationKind, ca as OperationSpec, cb as ParallelOpResult, cc as ParamKind, cd as ParamSpec, ce as ParamStructure, cf as PersistCtx, cg as PersistOrigin, ch as PlannedCommandMethod, ci as ProjectionMap, cj as ProjectionTransformOp, ck as PutOptions, cl as QueryContractMethodSpec, cm as QueryEnvelopeResult, cn as QueryKeyOf, co as QueryMethod, cp as QueryResult, cq as RangeConditionSpec, cr as ReadEnvelope, cs as ReadOpCtx, ct as ReadOpKind, cu as ReadOperationType, cv as ReadRouteDescriptor, cw as ReadRouteOptions, cx as ReadRouteResult, cy as RecordedCompose, cz as RelationBuilder, cA as RelationConsistency, cB as RelationLimitOptions, cC as RelationPattern, cD as RelationProjection, cE as RelationReadOptions, cF as RelationSelect, cG as RelationSpec, cH as RelationUpdateMode, cI as RelationWriteOptions, cJ as RequiresEffect, cK as Resolution, cL as RetryInfo, cM as RetryOperationKind, cN as SPEC_VERSION, cO as SegmentSpec, cP as SegmentedKey, cQ as SelectBuilder, cR as SelectOf, cS as SnapshotEffect, cT as StartingPosition, cU as StreamViewType, cV as StringParam, cW as TransactionContext, cX as TransactionItemType, cY as UniqueEffect, cZ as Updatable, c_ as UpdateOptions, c$ as ViewSourceSlice, d0 as WhenSpec, d1 as WriteCtx, d2 as WriteDescriptor, d3 as WriteEnvelope, d4 as WriteInput, d5 as WriteKind, d6 as WriteLifecyclePhase, d7 as WriteMiddleware, d8 as WriteOperationType, d9 as WriteRecorder, da as WriteResultProjection, db as attachModelClass, dc as buildDeleteInput, dd as buildMaintenanceGraph, de as buildPutInput, df as buildUpdateInput, dg as collectViewDefinitions, dh as compileFragment, di as compileMutationPlan, dj as compileSingleFragmentPlan, dk as cond, dl as contractOfMethodSpec, dm as definePlan, dn as entityWrites, dp as executeBatchGet, dq as executeBatchWrite, dr as executeCommandMethod, ds as executeDelete, dt as executeKeyedBatchGet, du as executePut, dv as executeQueryMethod, dw as executeRangeFanout, dx as executeTransaction, dy as executeUpdate, dz as from, dA as getEntityWrites, dB as gsi, dC as identity, dD as isColumn, dE as isCommandModelContract, dF as isCommandPlan, dG as isContractComposeNode, dH as isContractFromRef, dI as isContractKeyFieldRef, dJ as isContractKeyRef, dK as isContractParamRef, dL as isEntityWritesDefinition, dM as isKeySegment, dN as isLifecycleContract, dO as isMaintainTrigger, dP as isMutationFragment, dQ as isMutationInputRef, dR as isParam, dS as isPlannedCommandMethod, dT as isQueryModelContract, dU as isRetryableError, dV as isRetryableTransactionCancellation, dW as k, dX as key, dY as lifecyclePhaseForIntent, dZ as maintainTrigger, d_ as mintContractKeyFieldRef, d$ as mintContractParamRef, e0 as mutation, e1 as param, e2 as preview, e3 as publicCommandModel, e4 as publicQueryModel, e5 as query, e6 as resolveLifecycle, e7 as wholeKeysSentinel } from './types-CpCo8yHP.js';
|
|
3
3
|
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
|
|
4
4
|
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
|
|
5
5
|
|
|
@@ -378,6 +378,14 @@ declare function validateGsiAmbiguity(primaryKey: KeyDefinition | null, gsiDefin
|
|
|
378
378
|
interface ModelOptions {
|
|
379
379
|
table: string;
|
|
380
380
|
prefix?: string;
|
|
381
|
+
/**
|
|
382
|
+
* The model's maintenance kind (issue #152). Defaults to `'entity'` (a plain
|
|
383
|
+
* stored entity). `'materializedView'` / `'sparseView'` mark it a maintained view
|
|
384
|
+
* row whose `@maintainedFrom` declarations feed the maintenance graph. A
|
|
385
|
+
* `sparseView` requires every `@maintainedFrom` to carry a `when` predicate (the
|
|
386
|
+
* adapter validates this).
|
|
387
|
+
*/
|
|
388
|
+
kind?: ModelKind;
|
|
381
389
|
}
|
|
382
390
|
declare function model(options: ModelOptions): (target: Function, context: ClassDecoratorContext) => void;
|
|
383
391
|
|
|
@@ -481,9 +489,294 @@ declare const map: FieldDecorator<Record<string, unknown>>;
|
|
|
481
489
|
|
|
482
490
|
declare function embedded(modelFactory: () => new (...args: unknown[]) => unknown): (_value: undefined, context: ClassFieldDecoratorContext) => void;
|
|
483
491
|
|
|
484
|
-
|
|
492
|
+
/**
|
|
493
|
+
* Symbolic `(self, source) =>` evaluation for the `@maintainedFrom` view authoring
|
|
494
|
+
* and the versioned relation `pattern` union (issue #152).
|
|
495
|
+
*
|
|
496
|
+
* ## Why this module exists (existing-mechanism reuse, not a new invention)
|
|
497
|
+
*
|
|
498
|
+
* `key()` / `gsi()` already evaluate an author callback by handing it a **Proxy
|
|
499
|
+
* accessor** (`createColumnMap`, `src/select/column.ts`): any `c.<field>` access
|
|
500
|
+
* returns a branded {@link import('../select/column.js').Column} sentinel carrying
|
|
501
|
+
* the field NAME, never a real value — so the structure (which field is
|
|
502
|
+
* referenced, where) is captured verbatim and a value transform is structurally
|
|
503
|
+
* impossible. The maintained-authoring `(self, source) =>` callback is the SAME
|
|
504
|
+
* shape of problem (capture *which* source/self field fills *which* output slot,
|
|
505
|
+
* declaratively), so it reuses the SAME Proxy-sentinel mechanism, specialized to
|
|
506
|
+
* the two roots the maintained vocabulary needs:
|
|
507
|
+
*
|
|
508
|
+
* - **`source.<field>`** → a {@link SourceRef} sentinel whose `path` is the
|
|
509
|
+
* payload-rooted `$.entity.<field>` the existing maintenance IR
|
|
510
|
+
* ({@link import('../define/entity-writes.js').ProjectionTransform}) reads. This
|
|
511
|
+
* is the value position (a projected value / key value / order-by / predicate
|
|
512
|
+
* operand). Typed `keyof Source`.
|
|
513
|
+
* - **`self.<field>`** → a {@link SelfRef} sentinel naming a field of the view /
|
|
514
|
+
* relation-target model (the `collection.field` position — which view attribute
|
|
515
|
+
* holds the maintained list). Typed `keyof Self`.
|
|
516
|
+
*
|
|
517
|
+
* The output-attribute *names* (the keys of `keyBind` / `project`) are plain
|
|
518
|
+
* `keyof Self` string literals — NOT computed keys — exactly the "key = name
|
|
519
|
+
* (typed string), value = reference (proxy)" rule the issue fixes.
|
|
520
|
+
*
|
|
521
|
+
* The lowering target is UNCHANGED: a {@link SourceRef} lowers to the same
|
|
522
|
+
* `$.entity.<field>` path the old string-based builder produced, so the maintenance
|
|
523
|
+
* IR (`ViewSourceSlice` / `MaintainEffect`) is byte-identical — only the authoring
|
|
524
|
+
* surface (this symbolic capture) is new.
|
|
525
|
+
*/
|
|
526
|
+
|
|
527
|
+
/** Brand identifying a {@link SourceRef} (`source.<field>`) at runtime. */
|
|
528
|
+
declare const SOURCE_REF: unique symbol;
|
|
529
|
+
/** Brand identifying a {@link SelfRef} (`self.<field>`) at runtime. */
|
|
530
|
+
declare const SELF_REF: unique symbol;
|
|
531
|
+
/**
|
|
532
|
+
* A captured reference to a **source** field (`source.<field>`), the value
|
|
533
|
+
* position of the maintained vocabulary. Carries the field name and the
|
|
534
|
+
* payload-rooted `$.entity.<field>` {@link path} the maintenance IR reads. Branded
|
|
535
|
+
* so the adapter can distinguish a faithful reference from a literal and reject a
|
|
536
|
+
* coerced / mis-used reference loudly.
|
|
537
|
+
*/
|
|
538
|
+
interface SourceRef {
|
|
539
|
+
readonly [SOURCE_REF]: true;
|
|
540
|
+
/** The source field name (e.g. `authorId`). */
|
|
541
|
+
readonly field: string;
|
|
542
|
+
/** The payload-rooted source value path (`$.entity.<field>`). */
|
|
543
|
+
readonly path: string;
|
|
544
|
+
}
|
|
545
|
+
/**
|
|
546
|
+
* A captured reference to a **self** field (`self.<field>`), naming a field of the
|
|
547
|
+
* model being defined (the view / relation-target). Used in the `collection.field`
|
|
548
|
+
* position (which attribute holds the maintained list). Branded.
|
|
549
|
+
*/
|
|
550
|
+
interface SelfRef {
|
|
551
|
+
readonly [SELF_REF]: true;
|
|
552
|
+
/** The self (view / relation-target) field name (e.g. `latestPosts`). */
|
|
553
|
+
readonly field: string;
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* The typed `source` accessor handed to a `(self, source) =>` callback: one
|
|
557
|
+
* {@link SourceRef} per field of the source entity, each typed with the field's
|
|
558
|
+
* declared value type (so `preview(source.body, n)` type-checks against a string
|
|
559
|
+
* field and a key-value position type-checks against the bound view-key field).
|
|
560
|
+
*
|
|
561
|
+
* @typeParam S - The source entity instance type.
|
|
562
|
+
*/
|
|
563
|
+
type SourceProxy<S> = [unknown] extends [S] ? Readonly<Record<string, SourceRef>> : {
|
|
564
|
+
readonly [K in keyof S]-?: SourceRef & {
|
|
565
|
+
readonly __value?: S[K];
|
|
566
|
+
};
|
|
567
|
+
};
|
|
568
|
+
/**
|
|
569
|
+
* The typed `self` accessor handed to a `(self, source) =>` callback: one
|
|
570
|
+
* {@link SelfRef} per field of the model being defined. Used in the value position
|
|
571
|
+
* of `collection.field` (which self attribute holds the maintained collection).
|
|
572
|
+
*
|
|
573
|
+
* @typeParam T - The model (view / relation-target) instance type.
|
|
574
|
+
*/
|
|
575
|
+
type SelfProxy<T> = [unknown] extends [T] ? Readonly<Record<string, SelfRef>> : {
|
|
576
|
+
readonly [K in keyof T]-?: SelfRef & {
|
|
577
|
+
readonly __value?: T[K];
|
|
578
|
+
};
|
|
579
|
+
};
|
|
580
|
+
/**
|
|
581
|
+
* A projected value in a maintained `project` map: either a {@link SourceRef}
|
|
582
|
+
* (identity capture of a source field) or an explicit {@link ProjectionTransform}
|
|
583
|
+
* (e.g. `preview(source.body, 120)`). This is the value side of the "key = name,
|
|
584
|
+
* value = reference" rule; the key side is a `keyof Self` string literal.
|
|
585
|
+
*/
|
|
586
|
+
type ProjectionValue = SourceRef | ProjectionTransform;
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* `@maintainedFrom` — the class-level, decorator-declarative view authoring of
|
|
590
|
+
* issue #152 (the Contract-layer replacement for `defineView` / `ViewRegistry`).
|
|
591
|
+
*
|
|
592
|
+
* ## What it is
|
|
593
|
+
*
|
|
594
|
+
* A maintained **view** (`@model({ kind: 'materializedView' | 'sparseView' })`) is
|
|
595
|
+
* its own modelled row maintained from the lifecycle events of one or more source
|
|
596
|
+
* entities. Each source contributes via a CLASS-LEVEL `@maintainedFrom` decorator
|
|
597
|
+
* (stackable — multiple sources each fill different view fields). This is the
|
|
598
|
+
* `@model`/`@hasMany` collector流儀: each `@maintainedFrom` pushes a
|
|
599
|
+
* {@link MaintainedFromMetadata} into a module-level collector and `@model` drains
|
|
600
|
+
* it into `EntityMetadata.maintainedFrom`.
|
|
601
|
+
*
|
|
602
|
+
* ## Symbolic `(self, source) =>` evaluation (existing-mechanism reuse)
|
|
603
|
+
*
|
|
604
|
+
* The options are authored as a `(self, source) => ({...})` callback evaluated
|
|
605
|
+
* eagerly at decoration time with the SAME Proxy-sentinel mechanism `key()`/`gsi()`
|
|
606
|
+
* use (`src/decorators/maintained-symbolic.ts`):
|
|
607
|
+
*
|
|
608
|
+
* - `source.<field>` → a {@link SourceRef} (value position) lowering to
|
|
609
|
+
* `$.entity.<field>` — the exact path the old string builder produced, so the IR
|
|
610
|
+
* is byte-identical.
|
|
611
|
+
* - `self.<field>` → a {@link SelfRef} naming a view field (the `collection.field`
|
|
612
|
+
* position).
|
|
613
|
+
* - Object KEYS (`keyBind` / `project` left-hand side) stay `keyof Self` string
|
|
614
|
+
* literals (NOT computed keys).
|
|
615
|
+
* - `on: ['created' | 'updated' | 'removed'][]` — the source is the decorator's
|
|
616
|
+
* first argument, so the `'Post.created'` logical-name string is gone (the bug
|
|
617
|
+
* class #124/#130 hit is removed by construction).
|
|
618
|
+
*
|
|
619
|
+
* ## Order independence (issue #152 hardening)
|
|
620
|
+
*
|
|
621
|
+
* Stacking order carries NO meaning. The adapter
|
|
622
|
+
* (`src/relation/maintenance-view-adapter.ts`) rejects — at build time, loudly and
|
|
623
|
+
* symmetrically (same error whichever order the decorators are stacked) — any two
|
|
624
|
+
* `@maintainedFrom` declarations that write the SAME projection target, the SAME
|
|
625
|
+
* `collection.field`, or bind the SAME view-key field inconsistently. A legitimate
|
|
626
|
+
* multi-source view (different sources filling DIFFERENT fields) is fine.
|
|
627
|
+
*/
|
|
628
|
+
|
|
629
|
+
type AnyModelClass$1 = new (...args: any[]) => any;
|
|
630
|
+
type SourceFactory = () => AnyModelClass$1;
|
|
631
|
+
/**
|
|
632
|
+
* A map keyed by `keyof Self` (the typed view fields) with value type `V`. When
|
|
633
|
+
* `Self` is left at its `unknown` default (the un-annotated decorator), it widens to
|
|
634
|
+
* a permissive `Record<string, V>` so authoring works without an explicit generic;
|
|
635
|
+
* supply `Self` to get `keyof Self` key-name checking.
|
|
636
|
+
*/
|
|
637
|
+
type SelfKeyed<Self, V> = [unknown] extends [Self] ? Readonly<Record<string, V>> : {
|
|
638
|
+
readonly [K in keyof Self]?: V;
|
|
639
|
+
};
|
|
640
|
+
/**
|
|
641
|
+
* The author-facing options object a `@maintainedFrom` callback returns. Keys
|
|
642
|
+
* (`keyBind` / `project` left-hand side) are `keyof Self` string literals; values
|
|
643
|
+
* are symbolic {@link SourceRef} (`source.<field>`) / transforms / {@link SelfRef}
|
|
644
|
+
* (`self.<field>`). `collection` and `when` are mutually exclusive.
|
|
645
|
+
*
|
|
646
|
+
* @typeParam Self - The view model instance type (drives `keyof Self` keys).
|
|
647
|
+
*/
|
|
648
|
+
interface MaintainedFromOptions<Self = unknown> {
|
|
649
|
+
/** The lifecycle events of the source that maintain the view row. */
|
|
650
|
+
readonly on: readonly MaintainEvent[];
|
|
651
|
+
/**
|
|
652
|
+
* The view-row key binding: view-row key field (`keyof Self`) → a `source.<field>`
|
|
653
|
+
* reference resolving which view row this source event maintains.
|
|
654
|
+
*/
|
|
655
|
+
readonly keyBind: SelfKeyed<Self, SourceRef>;
|
|
656
|
+
/**
|
|
657
|
+
* The projection of the source payload into the view row: target attribute
|
|
658
|
+
* (`keyof Self`) → a `source.<field>` reference or a transform (`preview(...)`).
|
|
659
|
+
*/
|
|
660
|
+
readonly project: SelfKeyed<Self, ProjectionValue>;
|
|
661
|
+
/**
|
|
662
|
+
* Declares this source maintains a bounded, ordered COLLECTION slice of the view
|
|
663
|
+
* row. `field` is a `self.<field>` reference (which view attribute holds the
|
|
664
|
+
* list); `orderBy` is a `source.<field>` reference. Mutually exclusive with `when`.
|
|
665
|
+
*/
|
|
666
|
+
readonly collection?: {
|
|
667
|
+
readonly field: SelfRef;
|
|
668
|
+
readonly maxItems?: number;
|
|
669
|
+
readonly order?: 'ASC' | 'DESC';
|
|
670
|
+
readonly orderBy?: SourceRef;
|
|
671
|
+
};
|
|
672
|
+
/** Sparse-view membership predicate (sparseView kind). Mutually exclusive with `collection`. */
|
|
673
|
+
readonly when?: MembershipPredicate;
|
|
674
|
+
readonly consistency?: MaintainConsistency;
|
|
675
|
+
readonly updateMode?: MaintainUpdateMode;
|
|
676
|
+
}
|
|
677
|
+
/** The `(self, source) =>` symbolic callback evaluated at decoration time. */
|
|
678
|
+
type MaintainedFromCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => MaintainedFromOptions<Self>;
|
|
679
|
+
/**
|
|
680
|
+
* Build a {@link MembershipPredicate} for a sparse view. The view row is PUT when
|
|
681
|
+
* the predicate holds and DELETED when it flips false. The operand is a symbolic
|
|
682
|
+
* `source.<field>` reference (or a bare path string) lowered to `$.entity.<field>`.
|
|
683
|
+
*
|
|
684
|
+
* Named `whenMember` (not `when`) to avoid colliding with the transaction-condition
|
|
685
|
+
* `when` helper.
|
|
686
|
+
*
|
|
687
|
+
* @example `whenMember(source.status, 'eq', 'active')`
|
|
688
|
+
* @example `whenMember(source.archived, 'falsy')`
|
|
689
|
+
*/
|
|
690
|
+
declare function whenMember(operand: SourceRef | string, op: MembershipPredicateOp, value?: unknown): MembershipPredicate;
|
|
691
|
+
/**
|
|
692
|
+
* `@maintainedFrom(source, (self, source) => options)` — the class-level view
|
|
693
|
+
* maintainer decorator (issue #152). Stackable: apply once per source. Evaluates
|
|
694
|
+
* the symbolic callback at decoration time and records the lowered
|
|
695
|
+
* {@link MaintainedFromMetadata} into the collector for `@model` to drain.
|
|
696
|
+
*
|
|
697
|
+
* @typeParam Self - The view model instance type (typed `keyof Self` keys).
|
|
698
|
+
* @typeParam Source - The source entity instance type (typed `source.<field>`).
|
|
699
|
+
*
|
|
700
|
+
* @example
|
|
701
|
+
* ```ts
|
|
702
|
+
* @model({ table: 'AppTable', kind: 'materializedView' })
|
|
703
|
+
* @maintainedFrom(() => PostModel, (self, source) => ({
|
|
704
|
+
* keyBind: { userId: source.authorId, threadId: source.threadId },
|
|
705
|
+
* on: ['created', 'removed'],
|
|
706
|
+
* project: { lastPostAt: source.createdAt, textPreview: preview(source.body, 120) },
|
|
707
|
+
* collection: { field: self.latestPosts, orderBy: source.createdAt, order: 'DESC', maxItems: 20 },
|
|
708
|
+
* }))
|
|
709
|
+
* class UserThreadListModel extends DDBModel { … }
|
|
710
|
+
* ```
|
|
711
|
+
*/
|
|
712
|
+
declare function maintainedFrom<Self = unknown, Source = unknown>(source: SourceFactory, callback: MaintainedFromCallback<Self, Source>): (target: Function, context: ClassDecoratorContext) => void;
|
|
713
|
+
|
|
714
|
+
/**
|
|
715
|
+
* Versioned relation `pattern` discriminated union (issue #152, section B).
|
|
716
|
+
*
|
|
717
|
+
* Versioned is "a preset that re-uses the core snapshot effect", so it rides on the
|
|
718
|
+
* `@hasOne` / `@hasMany` `pattern` discriminator instead of a dedicated decorator:
|
|
719
|
+
*
|
|
720
|
+
* - `@hasOne(() => Latest, (self, source) => ({ pattern: 'versionedLatest', on, project }))`
|
|
721
|
+
* — a SINGLE maintained row, OVERWRITTEN per revision (keyed without the version).
|
|
722
|
+
* - `@hasMany(() => History, (self, source) => ({ pattern: 'versionedHistory', on, project }))`
|
|
723
|
+
* — one APPENDED row per revision (keyed WITH the version).
|
|
724
|
+
*
|
|
725
|
+
* ## Three type-level guards (issue #152 B (a)/(b)/(c))
|
|
726
|
+
*
|
|
727
|
+
* (a) Per-pattern fields — the options union is discriminated on `pattern`, so each
|
|
728
|
+
* member admits exactly its own fields.
|
|
729
|
+
* (b) Cardinality integrity — `versionedLatest` is only assignable to a `@hasOne`
|
|
730
|
+
* callback's return and `versionedHistory` only to `@hasMany`'s, enforced by the
|
|
731
|
+
* distinct callback option types {@link HasOneVersionedOptions} /
|
|
732
|
+
* {@link HasManyVersionedOptions} the two decorators accept.
|
|
733
|
+
* (c) Symbolic refs — `source.<field>` is `keyof Source` and `project` keys are
|
|
734
|
+
* `keyof Self`, via the shared {@link SourceProxy} / proxy-sentinel mechanism.
|
|
735
|
+
*
|
|
736
|
+
* Both lower to the SAME snapshot×2 IR the old `defineVersioned` produced (the
|
|
737
|
+
* adapter `src/relation/maintenance-view-adapter.ts` turns the recorded
|
|
738
|
+
* `RelationOptions.versioned` into `defineView`-shaped `ViewDefinition`s). The
|
|
739
|
+
* latest/history KEY binding is derived from the TARGET model's own key input fields
|
|
740
|
+
* (each bound from the same-named source field) — latest keys omit the version,
|
|
741
|
+
* history keys include it, by the two models' own `key` definitions.
|
|
742
|
+
*/
|
|
743
|
+
|
|
744
|
+
/** A versioned-latest options object (single overwritten row). */
|
|
745
|
+
interface VersionedLatestOptions<Self = unknown> {
|
|
746
|
+
readonly pattern: 'versionedLatest';
|
|
747
|
+
readonly on: readonly MaintainEvent[];
|
|
748
|
+
readonly project: SelfKeyed<Self, ProjectionValue>;
|
|
749
|
+
readonly consistency?: MaintainConsistency;
|
|
750
|
+
readonly updateMode?: MaintainUpdateMode;
|
|
751
|
+
}
|
|
752
|
+
/** A versioned-history options object (append-only per-revision rows). */
|
|
753
|
+
interface VersionedHistoryOptions<Self = unknown> {
|
|
754
|
+
readonly pattern: 'versionedHistory';
|
|
755
|
+
readonly on: readonly MaintainEvent[];
|
|
756
|
+
readonly project: SelfKeyed<Self, ProjectionValue>;
|
|
757
|
+
readonly consistency?: MaintainConsistency;
|
|
758
|
+
readonly updateMode?: MaintainUpdateMode;
|
|
759
|
+
}
|
|
760
|
+
/**
|
|
761
|
+
* The options a `@hasOne` versioned callback may return — `versionedLatest` ONLY.
|
|
762
|
+
* (Cardinality integrity: a `versionedHistory` on `@hasOne` is a type error.)
|
|
763
|
+
*/
|
|
764
|
+
type HasOneVersionedOptions<Self = unknown> = VersionedLatestOptions<Self>;
|
|
765
|
+
/**
|
|
766
|
+
* The options a `@hasMany` versioned callback may return — `versionedHistory` ONLY.
|
|
767
|
+
* (Cardinality integrity: a `versionedLatest` on `@hasMany` is a type error.)
|
|
768
|
+
*/
|
|
769
|
+
type HasManyVersionedOptions<Self = unknown> = VersionedHistoryOptions<Self>;
|
|
770
|
+
/** The `(self, source) =>` versioned callback for `@hasOne`. */
|
|
771
|
+
type HasOneVersionedCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => HasOneVersionedOptions<Self>;
|
|
772
|
+
/** The `(self, source) =>` versioned callback for `@hasMany`. */
|
|
773
|
+
type HasManyVersionedCallback<Self, Source> = (self: SelfProxy<Self>, source: SourceProxy<Source>) => HasManyVersionedOptions<Self>;
|
|
774
|
+
|
|
775
|
+
declare function hasMany(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (value: undefined, context: ClassFieldDecoratorContext) => void;
|
|
776
|
+
declare function hasMany<Self = unknown, Source = unknown>(targetFactory: () => new (...args: unknown[]) => unknown, callback: HasManyVersionedCallback<Self, Source>): (value: undefined, context: ClassFieldDecoratorContext) => void;
|
|
485
777
|
declare function belongsTo(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
|
|
486
|
-
declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (
|
|
778
|
+
declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (value: undefined, context: ClassFieldDecoratorContext) => void;
|
|
779
|
+
declare function hasOne<Self = unknown, Source = unknown>(targetFactory: () => new (...args: unknown[]) => unknown, callback: HasOneVersionedCallback<Self, Source>): (value: undefined, context: ClassFieldDecoratorContext) => void;
|
|
487
780
|
|
|
488
781
|
/**
|
|
489
782
|
* `@aggregate` — a **scalar-aggregate** field decorator (Epic #118 §5.2 counter /
|
|
@@ -1216,105 +1509,6 @@ declare function createMaintenanceDrain(opts?: MaintenanceDrainOptions): Mainten
|
|
|
1216
1509
|
*/
|
|
1217
1510
|
declare function createMaintenanceDrainHandler(opts?: MaintenanceDrainOptions): ChangeHandler;
|
|
1218
1511
|
|
|
1219
|
-
/**
|
|
1220
|
-
* External-projection **sink drain** (issue #132) — the asynchronous runtime for
|
|
1221
|
-
* `defineProjection` (`externalProjection`, Epic #118 §5.3 / RFC §4.A.8).
|
|
1222
|
-
*
|
|
1223
|
-
* A `defineProjection` declares a stream + idempotency projection of a source
|
|
1224
|
-
* entity into an EXTERNAL sink (BigQuery / S3 / OpenSearch / Neptune in
|
|
1225
|
-
* production). The transport is the CDC stream: the source entity's writes surface
|
|
1226
|
-
* as {@link ChangeEvent}s (real DynamoDB Streams in production, the
|
|
1227
|
-
* {@link import('./emulator.js').CdcEmulator} in dev/test), and THIS consumer
|
|
1228
|
-
* projects each event's source image and upserts it into the sink.
|
|
1229
|
-
*
|
|
1230
|
-
* ## At-least-once → exactly-once-effect via the idempotency key
|
|
1231
|
-
*
|
|
1232
|
-
* The CDC substrate delivers at-least-once (a single source event may be delivered
|
|
1233
|
-
* more than once). An external sink upsert is the ONE place a duplicate would
|
|
1234
|
-
* double-write, so the projection folds redelivery by the declared
|
|
1235
|
-
* `idempotencyKey` (a source attribute, e.g. `resultId`): the sink is an UPSERT
|
|
1236
|
-
* keyed by that value, so re-delivering the same source event overwrites the same
|
|
1237
|
-
* sink record rather than appending a second. This is the standard "make
|
|
1238
|
-
* at-least-once idempotent with a business key" pattern; the sink need only
|
|
1239
|
-
* support an idempotent put keyed by the idempotency key.
|
|
1240
|
-
*
|
|
1241
|
-
* ## The sink abstraction (dev/test vs production)
|
|
1242
|
-
*
|
|
1243
|
-
* {@link ProjectionSink} is the minimal contract a real sink adapter implements
|
|
1244
|
-
* (`upsert(key, record)` / `delete(key)`). Production wires a BigQuery / S3 /
|
|
1245
|
-
* OpenSearch adapter; dev/test uses {@link InMemoryProjectionSink}, an in-process
|
|
1246
|
-
* map that the integration tests assert convergence + idempotency against. The
|
|
1247
|
-
* drain itself is sink-agnostic — it resolves the projection, computes the key,
|
|
1248
|
-
* and calls the adapter.
|
|
1249
|
-
*/
|
|
1250
|
-
|
|
1251
|
-
/**
|
|
1252
|
-
* The minimal contract a projection sink adapter implements. An upsert is keyed by
|
|
1253
|
-
* the idempotency key (so a redelivery overwrites the same record), a delete
|
|
1254
|
-
* removes it (for a source `removed` event projected to the sink).
|
|
1255
|
-
*/
|
|
1256
|
-
interface ProjectionSink {
|
|
1257
|
-
/** Upsert the projected record under the idempotency key (idempotent). */
|
|
1258
|
-
upsert(key: string, record: Record<string, unknown>): void | Promise<void>;
|
|
1259
|
-
/** Remove the record under the idempotency key (for a projected `removed`). */
|
|
1260
|
-
delete?(key: string): void | Promise<void>;
|
|
1261
|
-
}
|
|
1262
|
-
/**
|
|
1263
|
-
* An in-process {@link ProjectionSink} for dev/test — a map keyed by the
|
|
1264
|
-
* idempotency key. Mirrors what a real sink (BigQuery / S3) does logically: an
|
|
1265
|
-
* upsert keyed by a business key folds at-least-once redelivery to one record. The
|
|
1266
|
-
* integration tests assert convergence + idempotency against {@link records}.
|
|
1267
|
-
*/
|
|
1268
|
-
declare class InMemoryProjectionSink implements ProjectionSink {
|
|
1269
|
-
/** The current sink contents, keyed by the idempotency key. */
|
|
1270
|
-
readonly records: Map<string, Record<string, unknown>>;
|
|
1271
|
-
/** Total upsert CALLS (including redelivered ones) — distinguishes calls from records. */
|
|
1272
|
-
private upserts;
|
|
1273
|
-
upsert(key: string, record: Record<string, unknown>): void;
|
|
1274
|
-
delete(key: string): void;
|
|
1275
|
-
/** The number of distinct sink records (the converged projection size). */
|
|
1276
|
-
size(): number;
|
|
1277
|
-
/** The total upsert calls (≥ size when redelivery occurred). */
|
|
1278
|
-
upsertCount(): number;
|
|
1279
|
-
/** Reset the sink (test). */
|
|
1280
|
-
reset(): void;
|
|
1281
|
-
}
|
|
1282
|
-
/** Options for {@link createProjectionSinkDrain}. */
|
|
1283
|
-
interface ProjectionSinkDrainOptions {
|
|
1284
|
-
/** The {@link ProjectionDefinition}s (`defineProjection`) this drain applies. */
|
|
1285
|
-
readonly projections: readonly ProjectionDefinition[];
|
|
1286
|
-
/** The external sink adapter the projected records are upserted into. */
|
|
1287
|
-
readonly sink: ProjectionSink;
|
|
1288
|
-
}
|
|
1289
|
-
/**
|
|
1290
|
-
* A projection sink drain (issue #132): a CDC consumer ({@link ChangeHandler}) that
|
|
1291
|
-
* projects each source event into the external sink, folding at-least-once delivery
|
|
1292
|
-
* by the projection's idempotency key. Construct via
|
|
1293
|
-
* {@link createProjectionSinkDrain}, then subscribe its {@link handler} to a
|
|
1294
|
-
* {@link import('./emulator.js').CdcEmulator} (dev/test) or a real Streams Lambda.
|
|
1295
|
-
*/
|
|
1296
|
-
declare class ProjectionSinkDrain {
|
|
1297
|
-
private readonly sink;
|
|
1298
|
-
/** Source-entity CLASS name (the `event.model` the capture seam records) → projections. */
|
|
1299
|
-
private readonly bySource;
|
|
1300
|
-
/** Per-(shard,seq) de-dup within one handler invocation (at-least-once). */
|
|
1301
|
-
private applied;
|
|
1302
|
-
constructor(opts: ProjectionSinkDrainOptions);
|
|
1303
|
-
/** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
|
|
1304
|
-
readonly handler: ChangeHandler;
|
|
1305
|
-
/** Project one source event into the sink for every matching projection. */
|
|
1306
|
-
private applyOne;
|
|
1307
|
-
/** Clear the per-delivery de-dup set (test reset). */
|
|
1308
|
-
reset(): void;
|
|
1309
|
-
}
|
|
1310
|
-
/** Create a {@link ProjectionSinkDrain} (issue #132). */
|
|
1311
|
-
declare function createProjectionSinkDrain(opts: ProjectionSinkDrainOptions): ProjectionSinkDrain;
|
|
1312
|
-
/**
|
|
1313
|
-
* Create just the CDC {@link ChangeHandler} for a projection sink drain — the form
|
|
1314
|
-
* to subscribe to an emulator or wire into a production Streams Lambda.
|
|
1315
|
-
*/
|
|
1316
|
-
declare function createProjectionSinkHandler(opts: ProjectionSinkDrainOptions): ChangeHandler;
|
|
1317
|
-
|
|
1318
1512
|
/**
|
|
1319
1513
|
* Per-key cursor envelope for batched `range` (`list`) contract methods (issue
|
|
1320
1514
|
* #62, CQRS single-service runtime; spec `docs/cqrs-contract.md`,
|
|
@@ -2802,4 +2996,4 @@ declare function assertBundleSerializable(bundle: BridgeBundle): void;
|
|
|
2802
2996
|
*/
|
|
2803
2997
|
declare function buildBridgeBundle(queries?: DefinitionMap, commands?: DefinitionMap, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
|
|
2804
2998
|
|
|
2805
|
-
export { AggregateOptions, AggregateValue, type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, CtxModel, DDBModel, DefinitionMap, DeleteInput, type DriftReport, DynamoDBOperation, DynamoExecutor, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition,
|
|
2999
|
+
export { AggregateOptions, AggregateValue, type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, CtxModel, DDBModel, DefinitionMap, DeleteInput, type DriftReport, DynamoDBOperation, DynamoExecutor, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition, type HasManyVersionedCallback, type HasManyVersionedOptions, type HasOneVersionedCallback, type HasOneVersionedOptions, Item, KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAINT_OUTBOX_PK_PREFIX, MAX_TRANSACT_ITEMS, MaintainConsistency, MaintainEffect, MaintainEvent, MaintainUpdateMode, type MaintainedFromCallback, type MaintainedFromOptions, MaintenanceDrain, type MaintenanceDrainOptions, type MaintenanceRebuildOptions, MaintenanceRebuilder, Manifest, MembershipPredicate, MembershipPredicateOp, MetadataRegistry, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, ProjectionTransform, type ProjectionValue, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, type RebuildResult, RelationMetadata, RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SelectableOf, type SelfProxy, type SelfRef, ShardId, type SourceProxy, type SourceRef, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type VersionedHistoryOptions, type VersionedLatestOptions, ViewDefinition, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, aggregate, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, count, createCdcEmulator, createDefaultLinter, createMaintenanceDrain, createMaintenanceDrainHandler, createMaintenanceRebuilder, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, maintainedFrom, map, max, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when, whenMember };
|