graphddb 0.5.1 → 0.5.2

package/dist/{types-B9rJ1z3H.d.ts → types-m1Ect6hG.d.ts}

@@ -724,11 +724,26 @@ interface GsiDefinitionMarker<T extends Record<string, unknown> = Record<string,
     readonly segmented: SegmentedKey;
     readonly inputFieldNames: string[];
     readonly unique: U;
+    /**
+     * Optional human-readable description of the GSI (issue #166, follow-up of #154),
+     * from `gsi(name, key, { description })`. Pure documentation — the registry copies
+     * it onto {@link GsiDefinition} (→ `manifest.json` + generated Python). Absent
+     * unless declared.
+     */
+    readonly description?: string;
     /** @internal Phantom field for type-level input type extraction. */
     readonly _phantom?: T;
 }
 interface GsiOptions {
     unique?: boolean;
+    /**
+     * Optional human-readable description of the index (issue #166, follow-up of #154).
+     * Pure documentation metadata — it does NOT affect the index key, projection, or any
+     * runtime behaviour. Propagated to `manifest.json` ({@link ManifestGsi.description})
+     * and surfaces as the docstring of a generated Python query method that reads through
+     * this index. Omit for byte-identical output.
+     */
+    description?: string;
 }
 type GsiBuilder<T extends Record<string, unknown>> = (c: {
     readonly [K in keyof T]-?: Column<T[K], T>;
@@ -3099,6 +3114,14 @@ interface ManifestKey {
 interface ManifestGsi extends ManifestKey {
     readonly indexName: string;
     readonly unique: boolean;
+    /**
+     * Optional human-readable description of the index (issue #166, follow-up of #154),
+     * from `gsi(name, key, { description })`. Pure documentation — absent unless declared,
+     * so a GSI with no description serializes byte-identically to the pre-#166 manifest.
+     * The Python codegen surfaces it as the docstring of a generated query method that
+     * reads through this index.
+     */
+    readonly description?: string;
 }
 interface ManifestRelation {
     readonly type: 'hasMany' | 'hasOne' | 'belongsTo';
@@ -3106,6 +3129,14 @@ interface ManifestRelation {
     readonly target: string;
     /** target field → source field (on this entity). */
     readonly keyBinding: Readonly<Record<string, string>>;
+    /**
+     * Optional human-readable description of the relation (issue #166, follow-up of
+     * #154), from `@hasMany/@belongsTo/@hasOne(..., { description })`. Pure documentation
+     * — absent unless declared, so a relation with no description serializes
+     * byte-identically to the pre-#166 manifest. The Python codegen surfaces it as a
+     * trailing `# …` comment on the relation's field in the generated result type.
+     */
+    readonly description?: string;
 }
 interface ManifestEntity {
     /** Declared (logical) table name. */
@@ -6525,6 +6556,24 @@ interface MaintainedFromMetadata {
     when?: MembershipPredicate;
     consistency?: MaintainConsistency;
     updateMode?: MaintainUpdateMode;
+    /**
+     * Optional human-readable description of this maintained-from source slice (issue
+     * #166, follow-up of #154), supplied via
+     * `@maintainedFrom(() => Source, (self, source) => ({ description, ... }))`. Pure
+     * documentation metadata — it does NOT affect the maintenance IR (`keyBind` /
+     * `project` / `on` / `collection` / `when`) or any runtime behaviour.
+     *
+     * NOTE (representation): the maintenance IR is deliberately kept OFF the
+     * serializable `manifest.json` / `operations.json` — the {@link Manifest} carries
+     * only the physical shape (table / keys / GSIs / relation navigation), NOT the
+     * maintenance graph (see `detectStreamMaintenance` in `src/codegen/cloudformation.ts`).
+     * There is therefore no manifest / operations / generated-Python site for a
+     * maintained-from source; this description is captured at the metadata layer only
+     * (mirroring where #154 captured its descriptions before propagation), available to
+     * any future consumer that DOES surface `@maintainedFrom` (e.g. the CDC-projection
+     * typed-consumer path, #153). Absent → byte-for-byte unchanged metadata.
+     */
+    description?: string;
 }
 interface KeyDefinition {
     /** The canonical structured key (PK/SK segment lists). */
@@ -6537,6 +6586,17 @@ interface GsiDefinition {
     segmented: SegmentedKey;
     inputFieldNames: string[];
     unique: boolean;
+    /**
+     * Optional human-readable description of the GSI (issue #166, follow-up of #154),
+     * supplied via `gsi(name, key, { description })`. Pure documentation metadata — it
+     * does NOT affect the index key, projection, or any runtime behaviour. When present
+     * it is propagated to the index entry in `manifest.json`
+     * ({@link ManifestGsi.description}) and surfaces as the docstring of any generated
+     * Python query method that reads through this index (a query carrying the GSI's
+     * `indexName`, when the query itself declares no description). Absent →
+     * byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
 }
 interface RelationLimitOptions {
     default: number;
@@ -6635,6 +6695,16 @@ type RelationProjection = Readonly<Record<string, ProjectionTransform | string>>
 interface RelationOptions {
     limit?: RelationLimitOptions;
     order?: 'ASC' | 'DESC';
+    /**
+     * Optional human-readable description of the relation (issue #166, follow-up of
+     * #154), supplied via `@hasMany/@belongsTo/@hasOne(() => T, keyBind, { description })`.
+     * Pure documentation metadata — it does NOT affect navigation, key binding, or any
+     * runtime behaviour. When present it is propagated to the relation entry in
+     * `manifest.json` ({@link ManifestRelation.description}) and surfaces as a trailing
+     * `# …` comment on the relation's field in the generated Python result TypedDict /
+     * dataclass. Absent → byte-for-byte unchanged output (backward compatible).
+     */
+    description?: string;
     /**
      * Named maintenance preset (Epic #118). Omitted = plain read-only navigation,
      * fully backward compatible with the historical relation decorators.