dynamodb-expression-builder 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,639 @@
+//#region src/operators.d.ts
+/**
+ * Wire-format (uppercase) operator union. INLINED copy of the app's
+ * `WireFilterOperator` (`src/schemas/dynamodb-schemas.ts`).
+ */
+type WireFilterOperator = 'EQ' | 'NE' | 'GT' | 'GE' | 'LT' | 'LE' | 'CONTAINS' | 'BEGINS_WITH' | 'BETWEEN' | 'IN' | 'EXISTS' | 'NOT_EXISTS' | 'SIZE_EQ' | 'SIZE_NE' | 'SIZE_LT' | 'SIZE_LE' | 'SIZE_GT' | 'SIZE_GE' | 'TYPE_EQ' | 'TYPE_NE';
+/**
+ * Data types the compat map reasons about. `L`/`M` are included even though the
+ * tool's Type selector doesn't expose them — they keep the compat table a
+ * faithful port of the app's (where indexed columns can report List/Map).
+ */
+type FilterDataType = 'S' | 'N' | 'B' | 'SS' | 'NS' | 'BS' | 'BOOL' | 'NULL' | 'L' | 'M';
+/**
+ * Single source-of-truth row for an operator. One row per operator; consumers
+ * read the metadata they need (wire form, value-shape gates, key/scan type
+ * compatibility).
+ */
+type OperatorDef = {
+  readonly value: string;
+  readonly label: string;
+  readonly symbol: string;
+  readonly wireForm: WireFilterOperator;
+  /** false → no RHS value (`exists`, `not_exists`). */
+  readonly requiresValue: boolean;
+  /** true → needs a second RHS value (`between` only). */
+  readonly requiresValue2: boolean;
+  /** true → type field is optional / defaults to `S` (`exists`, `size_*`). */
+  readonly typeOptional: boolean;
+  /** Key-eligible types. `[]` → scan-only, rejected by KeyConditionExpression. */
+  readonly keyAllowedTypes: ReadonlyArray<'S' | 'N' | 'B'>;
+  /** Scan-eligible types. Non-empty. */
+  readonly scanAllowedTypes: readonly FilterDataType[];
+};
+declare const FILTER_OPERATORS: readonly [{
+  readonly value: "=";
+  readonly label: "Equals (=)";
+  readonly symbol: "=";
+  readonly wireForm: "EQ";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["S", "N", "B"];
+  readonly scanAllowedTypes: readonly ["S", "N", "B", "SS", "NS", "BS", "BOOL", "NULL", "L", "M"];
+}, {
+  readonly value: "<>";
+  readonly label: "Not Equals (≠)";
+  readonly symbol: "≠";
+  readonly wireForm: "NE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "N", "B", "SS", "NS", "BS", "BOOL", "NULL", "L", "M"];
+}, {
+  readonly value: "<";
+  readonly label: "Less Than (<)";
+  readonly symbol: "<";
+  readonly wireForm: "LT";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["N"];
+  readonly scanAllowedTypes: readonly ["N"];
+}, {
+  readonly value: "<=";
+  readonly label: "Less Than or Equal (≤)";
+  readonly symbol: "≤";
+  readonly wireForm: "LE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["N"];
+  readonly scanAllowedTypes: readonly ["N"];
+}, {
+  readonly value: ">";
+  readonly label: "Greater Than (>)";
+  readonly symbol: ">";
+  readonly wireForm: "GT";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["N"];
+  readonly scanAllowedTypes: readonly ["N"];
+}, {
+  readonly value: ">=";
+  readonly label: "Greater Than or Equal (≥)";
+  readonly symbol: "≥";
+  readonly wireForm: "GE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["N"];
+  readonly scanAllowedTypes: readonly ["N"];
+}, {
+  readonly value: "contains";
+  readonly label: "Contains";
+  readonly symbol: "∋";
+  readonly wireForm: "CONTAINS";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "B", "SS", "NS", "BS", "L"];
+}, {
+  readonly value: "begins_with";
+  readonly label: "Begins With";
+  readonly symbol: "^";
+  readonly wireForm: "BEGINS_WITH";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["S", "B"];
+  readonly scanAllowedTypes: readonly ["S", "B"];
+}, {
+  readonly value: "between";
+  readonly label: "Between";
+  readonly symbol: "↔";
+  readonly wireForm: "BETWEEN";
+  readonly requiresValue: true;
+  readonly requiresValue2: true;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly ["N"];
+  readonly scanAllowedTypes: readonly ["N"];
+}, {
+  readonly value: "in";
+  readonly label: "In";
+  readonly symbol: "∈";
+  readonly wireForm: "IN";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "N"];
+}, {
+  readonly value: "exists";
+  readonly label: "Attribute Exists";
+  readonly symbol: "∃";
+  readonly wireForm: "EXISTS";
+  readonly requiresValue: false;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "N", "B", "SS", "NS", "BS", "BOOL", "NULL", "L", "M"];
+}, {
+  readonly value: "not_exists";
+  readonly label: "Attribute Not Exists";
+  readonly symbol: "∄";
+  readonly wireForm: "NOT_EXISTS";
+  readonly requiresValue: false;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "N", "B", "SS", "NS", "BS", "BOOL", "NULL", "L", "M"];
+}, {
+  readonly value: "size_eq";
+  readonly label: "Size Equals";
+  readonly symbol: "size =";
+  readonly wireForm: "SIZE_EQ";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["SS", "NS", "BS", "L", "M"];
+}, {
+  readonly value: "size_ne";
+  readonly label: "Size Not Equals";
+  readonly symbol: "size ≠";
+  readonly wireForm: "SIZE_NE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["SS", "NS", "BS", "L", "M"];
+}, {
+  readonly value: "size_lt";
+  readonly label: "Size Less Than";
+  readonly symbol: "size <";
+  readonly wireForm: "SIZE_LT";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["SS", "NS", "BS", "L", "M"];
+}, {
+  readonly value: "size_le";
+  readonly label: "Size Less Than or Equal";
+  readonly symbol: "size ≤";
+  readonly wireForm: "SIZE_LE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["SS", "NS", "BS", "L", "M"];
+}, {
+  readonly value: "size_gt";
+  readonly label: "Size Greater Than";
+  readonly symbol: "size >";
+  readonly wireForm: "SIZE_GT";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["SS", "NS", "BS", "L", "M"];
+}, {
+  readonly value: "size_ge";
+  readonly label: "Size Greater Than or Equal";
+  readonly symbol: "size ≥";
+  readonly wireForm: "SIZE_GE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: true;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["SS", "NS", "BS", "L", "M"];
+}, {
+  readonly value: "type_eq";
+  readonly label: "Type Equals";
+  readonly symbol: "type =";
+  readonly wireForm: "TYPE_EQ";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "N", "B", "SS", "NS", "BS", "BOOL", "NULL", "L", "M"];
+}, {
+  readonly value: "type_ne";
+  readonly label: "Type Not Equals";
+  readonly symbol: "type ≠";
+  readonly wireForm: "TYPE_NE";
+  readonly requiresValue: true;
+  readonly requiresValue2: false;
+  readonly typeOptional: false;
+  readonly keyAllowedTypes: readonly [];
+  readonly scanAllowedTypes: readonly ["S", "N", "B", "SS", "NS", "BS", "BOOL", "NULL", "L", "M"];
+}];
+/** Tightened union of every operator's lowercase internal value. */
+type OperatorValue = (typeof FILTER_OPERATORS)[number]['value'];
+/**
+ * O(1) registry lookup. Loose-keyed (`Record<string, OperatorDef>`) so boundary
+ * callers must guard `if (!def)` — the runtime value is `undefined` for unknown
+ * keys.
+ */
+declare const OPERATOR_BY_VALUE: Readonly<Record<string, OperatorDef>>;
+/** Key-eligible operators (KeyConditionExpression compatible). */
+declare const KEY_OPERATORS: readonly OperatorDef[];
+type FilterOperatorOption = (typeof FILTER_OPERATORS)[number];
+/**
+ * Operators applicable to a scan value of the given type. Undefined type → full
+ * list. Filters/conditions use this.
+ */
+declare function getCompatibleFilterOperators(type: FilterDataType | undefined): readonly FilterOperatorOption[];
+/**
+ * Key-eligible operators compatible with the given key type. Undefined → full
+ * key list. Range-key UI uses this (type-gated: N gets `<`/`between`, S/B get
+ * `begins_with`, all keys get `=`).
+ */
+declare function getCompatibleComparisonOperators(type: 'S' | 'N' | 'B' | undefined): readonly OperatorDef[];
+//#endregion
+//#region src/types.d.ts
+/**
+ * Value type tags the tool exposes. Mirrors the app's filter Type selector
+ * minus `L`/`M` (no nested List/Map in v1 — see docs/plans/…expression-builder).
+ */
+type DdbScalarType = 'S' | 'N' | 'B' | 'BOOL' | 'SS' | 'NS' | 'BS' | 'NULL';
+/** The set-typed tags, which carry members in `values` rather than `value`. */
+declare const SET_TYPES: readonly ["SS", "NS", "BS"];
+type SetType = (typeof SET_TYPES)[number];
+declare function isSetType(type: DdbScalarType): type is SetType;
+/**
+ * The scalar element type of a set tag (SS→S, NS→N, BS→B); identity for every
+ * scalar. `contains(path, operand)` takes a SCALAR operand even when `path` is a
+ * set (it tests membership), so the set-typed tag must marshal its ELEMENT type
+ * there — never `{SS:[…]}`, which DynamoDB rejects.
+ */
+declare function elementType(type: DdbScalarType): DdbScalarType;
+/**
+ * A value carried with its DynamoDB type tag. `value` holds the scalar string
+ * representation (S text; N numeric string; B base64; BOOL `'true'`/`'false'`;
+ * NULL unused). `values` holds the members of a set type (SS/NS/BS). Exactly
+ * one is meaningful per `type`; emitters branch on the tag, not the runtime.
+ */
+interface TypedValue {
+  type: DdbScalarType;
+  value: string;
+  /** Members for set types (SS/NS/BS). Undefined for scalars. */
+  values?: string[];
+}
+/**
+ * Build a {@link TypedValue} from a tag + raw entry. Set types take an explicit
+ * member array (falling back to the single `value` as one member); scalars take
+ * the string; NULL ignores the payload.
+ */
+declare function makeTypedValue(type: DdbScalarType, value: string, values?: string[]): TypedValue;
+/**
+ * A filter (Scan/Query) or condition (Update/Put/Delete) predicate row, as the
+ * bespoke UI emits it. `operator` is the lowercase internal value from
+ * `operators.ts` (`'='`, `'begins_with'`, …); the builder maps it to its wire
+ * form before compiling. `type` tags the RHS value(s).
+ */
+interface FilterRow {
+  field: string;
+  operator: OperatorValue;
+  type: DdbScalarType;
+  /** RHS scalar (unused for `exists`/`not_exists`; first bound for `between`). */
+  value: string;
+  /** Second bound for `between`. */
+  value2?: string;
+  /** Members for `in` (and set-typed single comparisons). */
+  values?: string[];
+}
+/** A primary-key attribute (GetItem/Delete Key map; Query hash key). */
+interface KeyAttr {
+  field: string;
+  /** Keys are always scalar S/N/B, but typed as the full union for reuse. */
+  type: DdbScalarType;
+  value: string;
+}
+/** Query range-key condition (a key-eligible operator + value[s]). */
+interface RangeKeyCondition {
+  field: string;
+  type: DdbScalarType;
+  operator: OperatorValue;
+  value: string;
+  /** Second bound for `between`. */
+  value2?: string;
+}
+/** A Put item attribute carrying its type tag. */
+interface ItemAttr {
+  field: string;
+  type: DdbScalarType;
+  value: string;
+  /** Members for set types. */
+  values?: string[];
+}
+/** SET-clause idioms (the only action kind with sub-modes). */
+type SetOperation = 'assign' | 'if_not_exists' | 'add' | 'subtract' | 'list_append' | 'list_prepend';
+type UpdateActionKind = 'SET' | 'REMOVE' | 'ADD' | 'DELETE';
+/**
+ * A single UpdateExpression action. `SET` carries a `setOp` idiom; `REMOVE`
+ * targets an attribute (optionally a list element via `index`); `ADD`/`DELETE`
+ * carry a number (ADD) or set (ADD/DELETE) value.
+ */
+interface UpdateAction {
+  kind: UpdateActionKind;
+  field: string;
+  /** SET only: which SET idiom. */
+  setOp?: SetOperation;
+  /** RHS value (SET except plain index removal; ADD; DELETE). */
+  value?: TypedValue;
+  /** List-element index for REMOVE (`#a[2]`). */
+  index?: number;
+}
+/** The six operations the builder supports. */
+type DdbOperation = 'GetItem' | 'Query' | 'Scan' | 'Update' | 'Put' | 'Delete';
+/**
+ * The whole builder state — one config covering every operation. Sub-parts are
+ * optional; `buildRequest` reads only the ones an operation uses (GetItem→key;
+ * Query→hashKey[+rangeKey][+filters]; Scan→filters; Update→key+updates[+conditions];
+ * Put→item[+conditions]; Delete→key[+conditions]). Serialised whole into the
+ * single `state` URL param.
+ */
+interface BuilderConfig {
+  operation: DdbOperation;
+  tableName: string;
+  indexName?: string;
+  /**
+   * Base-table PK/SK NAMES + TYPES only (never values). Lets a Scan or GSI-query
+   * emitter scaffold the table's REAL key schema instead of a `// TODO`
+   * placeholder — the request's own key belongs to the GSI (or is absent for a
+   * Scan), so the base schema must ride along separately. Absent when the base
+   * schema isn't known (the stateless expression tool, or table info not yet
+   * loaded); emitters fall back to the placeholder then.
+   */
+  baseKeySchema?: {
+    hashKey: {
+      field: string;
+      type: DdbScalarType;
+    };
+    rangeKey?: {
+      field: string;
+      type: DdbScalarType;
+    };
+  };
+  /** Query hash key (EQ). */
+  hashKey?: KeyAttr;
+  /** Query range key condition. */
+  rangeKey?: RangeKeyCondition;
+  /** GetItem/Update/Delete exact primary key attrs (hash[+range]). */
+  key?: KeyAttr[];
+  /** Scan/Query filter predicates. */
+  filters?: FilterRow[];
+  /** Update/Put/Delete write conditions. */
+  conditions?: FilterRow[];
+  /** Update actions. */
+  updates?: UpdateAction[];
+  /** Put item attributes. */
+  item?: ItemAttr[];
+  /** GetItem/Query/Scan projected attribute names. */
+  projection?: string[];
+  /** Query/Scan `Limit` — max items EVALUATED per request (positive integer). */
+  limit?: number;
+  /**
+   * Query sort order. Only `false` (descending) is carried through — `true` is
+   * the DynamoDB default, and emitting it would just be noise in the snippet.
+   */
+  scanIndexForward?: boolean;
+  /** GetItem/Query/Scan strongly-consistent read (only `true` is carried). */
+  consistentRead?: boolean;
+  /**
+   * Query/Scan resume point — the `LastEvaluatedKey` of a previous page, as
+   * typed key attrs (hash[+range]). Compiled into `ExclusiveStartKey`.
+   */
+  exclusiveStartKey?: KeyAttr[];
+}
+/**
+ * The canonical, fully-resolved request every emitter formats. Expression
+ * strings reference `#`/`:` placeholders resolved by `names`/`typedValues`;
+ * empty maps are omitted. `key`/`item` are direct name→value maps (no
+ * placeholders). `config` is the raw model retained for PartiQL, which builds
+ * literals rather than placeholders.
+ */
+interface CanonicalRequest {
+  operation: DdbOperation;
+  tableName: string;
+  indexName?: string;
+  key?: Record<string, TypedValue>;
+  item?: Record<string, TypedValue>;
+  keyConditionExpression?: string;
+  filterExpression?: string;
+  updateExpression?: string;
+  conditionExpression?: string;
+  projectionExpression?: string;
+  names?: Record<string, string>;
+  typedValues?: Record<string, TypedValue>;
+  /** Query/Scan `Limit` (positive integer; present only when set). */
+  limit?: number;
+  /** Present ONLY as `false` (descending Query) — the default `true` is omitted. */
+  scanIndexForward?: boolean;
+  /** Present ONLY as `true` (strongly-consistent read). */
+  consistentRead?: boolean;
+  /** Query/Scan resume point (typed name→value map, like `key`). */
+  exclusiveStartKey?: Record<string, TypedValue>;
+  config: BuilderConfig;
+}
+//#endregion
+//#region src/filter-expressions.d.ts
+/** Namespacing prefix so filter and condition placeholders never collide. */
+type PredicatePrefix = 'filter' | 'cond';
+interface PredicateExpression {
+  expression: string;
+  names: Record<string, string>;
+  typedValues: Record<string, TypedValue>;
+}
+/**
+ * Compile a list of predicate rows into one `… AND …` expression plus the
+ * fresh names/typedValues maps it references. Returns null for an empty list.
+ * Callers (buildRequest) merge the maps; this function never mutates shared
+ * state.
+ */
+declare function buildFilterExpressions(rows: FilterRow[], prefix: PredicatePrefix): PredicateExpression | null;
+//#endregion
+//#region src/key-command.d.ts
+interface KeyConditionResult {
+  expression: string;
+  names: Record<string, string>;
+  typedValues: Record<string, TypedValue>;
+}
+/**
+ * Build a Query KeyConditionExpression from a hash key (always EQ) plus an
+ * optional range-key condition. Captures value types.
+ */
+declare function buildKeyConditionExpression(hashKey: KeyAttr, rangeKey?: RangeKeyCondition): KeyConditionResult;
+/**
+ * Build the plain typed Key map (GetItem/Update/Delete) — real attribute names
+ * mapped to typed values, no expression placeholders.
+ */
+declare function buildKeyMap(keys: KeyAttr[]): Record<string, TypedValue>;
+//#endregion
+//#region src/build-request.d.ts
+/**
+ * Assemble a {@link CanonicalRequest} from a builder config. Pure: reads only the
+ * config sub-parts the operation uses, merges the sub-builders' maps, and omits
+ * any map that ended up empty. Throws (fail loud) when a required part is missing
+ * (a Query without a hash key) rather than emitting a malformed request.
+ */
+declare function buildRequest(config: BuilderConfig): CanonicalRequest;
+//#endregion
+//#region src/build-update-expression.d.ts
+interface UpdateExpressionResult {
+  expression: string;
+  names: Record<string, string>;
+  typedValues: Record<string, TypedValue>;
+}
+/**
+ * Compile update actions into one UpdateExpression. Returns null for an empty
+ * list. Callers (buildRequest) merge the returned maps; this never mutates
+ * shared state. Actions are grouped by kind into the canonical
+ * `SET … REMOVE … ADD … DELETE …` order while preserving each action's input
+ * order within its clause.
+ */
+declare function buildUpdateExpression(actions: UpdateAction[]): UpdateExpressionResult | null;
+//#endregion
+//#region src/emit/marshal.d.ts
+/** A single DynamoDB-JSON AttributeValue (the v1 scalar/set subset). */
+type AttributeValue = {
+  S: string;
+} | {
+  N: string;
+} | {
+  B: string;
+} | {
+  BOOL: boolean;
+} | {
+  SS: string[];
+} | {
+  NS: string[];
+} | {
+  BS: string[];
+} | {
+  NULL: true;
+};
+/** Build an AttributeValue from a value's type tag (not its runtime type). */
+declare function typedValueToAv(tv: TypedValue): AttributeValue;
+/** Marshal a whole placeholder/attr map (`:v`→typed, or name→typed) to AVs. */
+declare function typedMapToAvMap(map: Record<string, TypedValue>): Record<string, AttributeValue>;
+/**
+ * Does this request carry any binary (`B`/`BS`) value? The SDK v3 / boto3
+ * emitters use this to decide whether to emit binary-decoding (a `Uint8Array`
+ * expression / an `import base64`).
+ */
+declare function hasBinaryValue(request: CanonicalRequest): boolean;
+//#endregion
+//#region src/emit/sdk-v3.d.ts
+/** Build the command params object (key order matches typical SDK usage). */
+declare function buildSdkV3Params(request: CanonicalRequest): Record<string, unknown>;
+/** Emit the `new <Op>Command({...})` source snippet for a canonical request. */
+declare function emitSdkV3(request: CanonicalRequest): string;
+/** The `@aws-sdk/client-dynamodb` command class name for an operation. */
+declare function sdkV3CommandName(operation: DdbOperation): string;
+/**
+ * Render an arbitrary params value as the same pretty-printed JS literal
+ * `emitSdkV3` embeds (B/BS members as `Uint8Array` expressions). Exported for
+ * the query-builder program emitter, which composes its own statements around
+ * the literal (client init + pagination loop) instead of a bare `new Command`.
+ */
+declare function renderJsValue(value: unknown, indent?: number): string;
+//#endregion
+//#region src/emit/cli.d.ts
+/** Emit the multi-line `aws dynamodb <op>` command for a canonical request. */
+declare function emitCli(request: CanonicalRequest): string;
+//#endregion
+//#region src/emit/boto3.d.ts
+/**
+ * Render a params value as the same Python literal `emitBoto3` embeds
+ * (`True`/`False`/`None`, B/BS as `base64.b64decode(...)`). Exported for the
+ * query-builder program emitter, which renders a `params` dict for its
+ * LastEvaluatedKey pagination loop.
+ */
+declare function renderPyValue(value: unknown): string;
+/** The low-level boto3 client method name for an operation. */
+declare function boto3MethodName(operation: DdbOperation): string;
+/** Emit the runnable boto3 snippet (client + method call) for a canonical request. */
+declare function emitBoto3(request: CanonicalRequest): string;
+//#endregion
+//#region src/emit/partiql.d.ts
+/** Either a finished statement or an honest reason PartiQL can't express it. */
+type PartiqlResult = {
+  ok: true;
+  statement: string;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Emit a PartiQL statement for a canonical request, or an honest
+ * `{ ok: false, reason }` when the request has no faithful PartiQL form.
+ */
+declare function emitPartiql(request: CanonicalRequest): PartiqlResult;
+//#endregion
+//#region src/emit/java.d.ts
+/** The model request class name for an operation (`QueryRequest`, …). */
+declare function javaRequestClassName(operation: DdbOperation): string;
+/** The `DynamoDbClient` method name for an operation (`query`, …). */
+declare function javaClientMethodName(operation: DdbOperation): string;
+/** Emit the bare `<Op>Request.builder()…build()` snippet for a canonical request. */
+declare function emitJava(request: CanonicalRequest): string;
+//#endregion
+//#region src/emit/go.d.ts
+/** The `dynamodb.<Op>Input` struct name for an operation. */
+declare function goInputTypeName(operation: DdbOperation): string;
+/** The `dynamodb.Client` method name for an operation. */
+declare function goClientMethodName(operation: DdbOperation): string;
+/** Emit the bare `&dynamodb.<Op>Input{…}` snippet for a canonical request. */
+declare function emitGo(request: CanonicalRequest): string;
+//#endregion
+//#region src/emit/dotnet.d.ts
+/** The model request class name for an operation (`QueryRequest`, …). */
+declare function dotnetRequestClassName(operation: DdbOperation): string;
+/** The async client method name for an operation (`QueryAsync`, …). */
+declare function dotnetClientMethodName(operation: DdbOperation): string;
+/** Emit the bare `new <Op>Request { … }` snippet for a canonical request. */
+declare function emitDotnet(request: CanonicalRequest): string;
+//#endregion
+//#region src/emit/ddbtoolbox.d.ts
+/**
+ * Emit the runnable dynamodb-toolbox program for a Query/Scan canonical request.
+ * `paginate` wraps the send in a `LastEvaluatedKey` loop (dynamodb-toolbox's
+ * `send()` returns `{ Items, LastEvaluatedKey }` and takes `exclusiveStartKey`).
+ */
+declare function emitDdbToolboxProgram(request: CanonicalRequest, paginate: boolean): string;
+//#endregion
+//#region src/program.d.ts
+/**
+ * The query tool's whole state: a Query/Scan {@link BuilderConfig} plus the one
+ * PROGRAM-level knob the request itself doesn't carry — whether the emitted
+ * code loops on `LastEvaluatedKey` to fetch every page.
+ */
+interface QueryToolConfig extends BuilderConfig {
+  /** Emit the fetch-all-pages pagination loop (default: single request). */
+  paginate?: boolean;
+}
+type QueryProgramFormat = 'sdk' | 'cli' | 'boto3' | 'partiql' | 'java' | 'go' | 'dotnet' | 'ddbtoolbox';
+/** A runnable program, or an honest reason the format can't express it. */
+type ProgramResult = {
+  ok: true;
+  code: string;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Emit the runnable program for a Query/Scan config in the given format.
+ * Throws on a non-read operation (the widget never produces one — programmer
+ * error, mirroring `buildRequest`'s fail-loud posture) and propagates
+ * `buildRequest`'s build errors (e.g. a Query without a hash key) for the
+ * caller to surface as a note.
+ */
+declare function emitQueryProgram(config: QueryToolConfig, format: QueryProgramFormat): ProgramResult;
+//#endregion
+export { type AttributeValue, type BuilderConfig, type CanonicalRequest, type DdbOperation, type DdbScalarType, FILTER_OPERATORS, type FilterDataType, type FilterOperatorOption, type FilterRow, type ItemAttr, KEY_OPERATORS, type KeyAttr, type KeyConditionResult, OPERATOR_BY_VALUE, type OperatorDef, type OperatorValue, type PartiqlResult, type PredicateExpression, type PredicatePrefix, type ProgramResult, type QueryProgramFormat, type QueryToolConfig, type RangeKeyCondition, SET_TYPES, type SetOperation, type SetType, type TypedValue, type UpdateAction, type UpdateExpressionResult, type WireFilterOperator, boto3MethodName, buildFilterExpressions, buildKeyConditionExpression, buildKeyMap, buildRequest, buildSdkV3Params, buildUpdateExpression, dotnetClientMethodName, dotnetRequestClassName, elementType, emitBoto3, emitCli, emitDdbToolboxProgram, emitDotnet, emitGo, emitJava, emitPartiql, emitQueryProgram, emitSdkV3, getCompatibleComparisonOperators, getCompatibleFilterOperators, goClientMethodName, goInputTypeName, hasBinaryValue, isSetType, javaClientMethodName, javaRequestClassName, makeTypedValue, renderJsValue, renderPyValue, sdkV3CommandName, typedMapToAvMap, typedValueToAv };