graphddb-runtime 0.2.0__tar.gz → 0.2.2__tar.gz

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.2.0
+Version: 0.2.2
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/graphddb_runtime/filters.py

@@ -2,9 +2,11 @@
 
 Port of the TypeScript ``compileFilterExpression``
 (``src/expression/filter-expression.ts``). The declarative tree carried in a
-query spec's ``filter.declarative`` is JSON-safe (the TS bridge guard rejects
-the non-serializable ``cond`` escape hatch), so only the operator/logical forms
-are handled here.
+query spec's ``filter.declarative`` is JSON-safe, so only the operator/logical
+forms are handled here. (A read-side ``cond`` escape hatch is not serialized into
+``filter.declarative``; a *write*-side ``cond`` rides the separate ``raw``
+condition spec — issue #114-B — rendered in ``runtime.py`` / ``transactions.py``,
+not here.)
 
 Names are ``#``-aliased columns (reused per distinct column); values are
 ``:``-aliased parameters — no literal interpolation. The result is returned in

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/graphddb_runtime/runtime.py

@@ -64,6 +64,53 @@ def _normalize_template(template: Optional[str]) -> Optional[str]:
     return _PLACEHOLDER_RE.sub("\x00", template)
 
 
+def _resolve_condition_leaf(value: Any, params: Mapping[str, Any]) -> Any:
+    """Resolve one declarative-condition operand leaf (issue #114-A).
+
+    A ``{"$param": name}`` marker is replaced by the **typed** caller-param value
+    (so a numeric comparison stays numeric); a native literal is returned as-is.
+    """
+    if isinstance(value, dict) and isinstance(value.get("$param"), str):
+        name = value["$param"]
+        if name not in params or params[name] is None:
+            raise KeyError(f"condition references unbound parameter '{name}'")
+        return params[name]
+    return value
+
+
+def _resolve_condition_tree(node: Any, params: Mapping[str, Any]) -> Any:
+    """Resolve every ``{"$param"}`` marker in a serialized condition tree.
+
+    Walks the JSON-safe operator tree the TS planner emits (field operator
+    objects + ``and`` / ``or`` / ``not`` groups), substituting param markers with
+    typed caller-param values, and returns a tree shaped exactly like a
+    declarative ``filter`` so :func:`compile_filter` compiles it identically.
+    """
+    out: Dict[str, Any] = {}
+    for key, value in node.items():
+        if key in ("and", "or"):
+            out[key] = [_resolve_condition_tree(s, params) for s in value]
+        elif key == "not":
+            out[key] = _resolve_condition_tree(value, params)
+        else:
+            ops: Dict[str, Any] = {}
+            for op, op_val in value.items():
+                if op == "between":
+                    lo, hi = op_val
+                    ops[op] = [
+                        _resolve_condition_leaf(lo, params),
+                        _resolve_condition_leaf(hi, params),
+                    ]
+                elif op == "in":
+                    ops[op] = [_resolve_condition_leaf(v, params) for v in op_val]
+                elif op == "attributeExists":
+                    ops[op] = op_val
+                else:
+                    ops[op] = _resolve_condition_leaf(op_val, params)
+            out[key] = ops
+    return out
+
+
 def _present(records: Any) -> List[Dict[str, Any]]:
     """The present (non-``None``, dict) parent records from a result collection.
 
@@ -1602,6 +1649,17 @@ class GraphDDBRuntime:
             values[v] = self._serializer.serialize(resolve_template(tmpl, params))
             sets.append(f"{n} = {v}")
 
+        # GSI key re-derivation (issue #115): an UpdateItem that changes a GSI's
+        # composing field MUST re-derive its `<index>PK`/`<index>SK` or the index
+        # silently rots — exactly as the TS `buildUpdateInput` does. The available
+        # values are the caller `params` (key fields ∪ change fields); a GSI is
+        # affected when at least one of its template placeholders is a changed
+        # field. An affected GSI whose composing fields are not all available
+        # throws (mirroring the base-table partial-key throw).
+        self._append_gsi_rederive_sets(
+            command_id, spec, params, names, values, sets
+        )
+
         request: Dict[str, Any] = {
             "TableName": self._physical_table(spec["tableName"]),
             "Key": key,
@@ -1613,6 +1671,66 @@ class GraphDDBRuntime:
         self._apply_condition(spec, request, params)
         self._call(command_id, self._client.update_item, request)
 
+    def _append_gsi_rederive_sets(
+        self,
+        command_id: str,
+        spec: Mapping[str, Any],
+        params: Mapping[str, Any],
+        names: Dict[str, str],
+        values: Dict[str, Any],
+        sets: List[str],
+    ) -> None:
+        """Re-derive every affected GSI key into the UpdateExpression (issue #115).
+
+        Mirrors the TS ``buildUpdateInput``: a GSI is *affected* when at least one
+        of its ``inputFields`` is a changed field; an affected GSI re-derives its
+        ``<index>PK``/``<index>SK`` from the available caller params (key fields ∪
+        change fields). An affected GSI whose ``inputFields`` are not all available
+        throws — the SAME explicit error the TS path raises — rather than letting
+        the index silently rot.
+        """
+        entity_meta = self._entities.get(spec.get("entity"), {})
+        gsis = entity_meta.get("gsis", [])
+        if not gsis:
+            return
+        changed = set(spec.get("changes", {}).keys())
+        if not changed:
+            return
+        # Available value map: caller params with a non-None value.
+        available = {k: v for k, v in params.items() if v is not None}
+        gsi_index = 0
+        for gsi in gsis:
+            input_fields = list(gsi.get("inputFields", []))
+            if not any(f in changed for f in input_fields):
+                continue  # unaffected GSI — never touched (non-regression).
+            missing = [f for f in input_fields if f not in available]
+            if missing:
+                changed_in_gsi = [f for f in input_fields if f in changed]
+                raise GraphDDBError(
+                    f"{command_id}: updating "
+                    f"{', '.join(repr(f) for f in changed_in_gsi)} affects index "
+                    f"'{gsi['indexName']}' (also depends on "
+                    f"{', '.join(repr(f) for f in missing)}); provide "
+                    f"{'them' if len(missing) > 1 else 'it'}, or use "
+                    f"read-modify-write."
+                )
+            index = gsi["indexName"]
+            pk_tmpl = gsi.get("pkTemplate")
+            sk_tmpl = gsi.get("skTemplate")
+            if pk_tmpl is not None:
+                n = f"#gsi{gsi_index}pk"
+                v = f":gsi{gsi_index}pk"
+                names[n] = f"{index}PK"
+                values[v] = self._serializer.serialize(self._fill(pk_tmpl, available))
+                sets.append(f"{n} = {v}")
+            if sk_tmpl is not None:
+                n = f"#gsi{gsi_index}sk"
+                v = f":gsi{gsi_index}sk"
+                names[n] = f"{index}SK"
+                values[v] = self._serializer.serialize(self._fill(sk_tmpl, available))
+                sets.append(f"{n} = {v}")
+            gsi_index += 1
+
     def _run_delete_item(
         self, command_id: str, spec: Mapping[str, Any], params: Mapping[str, Any]
     ) -> None:
@@ -1668,6 +1786,35 @@ class GraphDDBRuntime:
                 values[v] = self._serializer.serialize(resolved)
                 clauses.append(f"{n} = {v}")
             request["ConditionExpression"] = " AND ".join(clauses)
+        elif kind == "expr":
+            # The declarative operator tree (issue #114-A): resolve each
+            # ``{"$param": name}`` marker to its typed caller-param value, then
+            # compile the tree to a ConditionExpression with the SAME mechanics as
+            # the read-side filter (``compile_filter``) so TS and Python emit an
+            # identical expression / semantics. ``compile_filter`` allocates
+            # ``#f`` / ``:vf`` aliases that never collide with the update ``#c`` /
+            # ``:c`` namespace, so the compiled names/values merge cleanly.
+            concrete = _resolve_condition_tree(condition["declarative"], params)
+            compiled = compile_filter(concrete, self._serializer)
+            if compiled is None:
+                return
+            names.update(compiled["ExpressionAttributeNames"])
+            values = request.setdefault("ExpressionAttributeValues", {})
+            values.update(compiled["ExpressionAttributeValues"])
+            request["ConditionExpression"] = compiled["FilterExpression"]
+        elif kind == "raw":
+            # A raw ``cond`` write condition (issue #114-B): the expression and
+            # the ``#cr_*`` name aliases are finished; bind each ``:crN`` value to
+            # its literal, or — when it is a ``{"$param": name}`` marker — to the
+            # typed caller-param value, then serialize. ``#cr_*`` / ``:cr*`` never
+            # collide with the update namespace, so they merge cleanly. The
+            # expression mirrors the TS ``serializeRawCondition`` output verbatim.
+            names.update(condition["names"])
+            values = request.setdefault("ExpressionAttributeValues", {})
+            for alias, raw_val in condition["values"].items():
+                resolved = _resolve_condition_leaf(raw_val, params)
+                values[alias] = self._serializer.serialize(resolved)
+            request["ConditionExpression"] = condition["expression"]
 
     def _add_key_attributes(
         self, entity_name: str, item: Dict[str, Any], params: Mapping[str, Any]

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/graphddb_runtime/transactions.py

@@ -18,6 +18,8 @@ from __future__ import annotations
 import re
 from typing import Any, Dict, List, Mapping, Optional
 
+from .filters import compile_filter
+
 _PLACEHOLDER_RE = re.compile(r"\{[^{}]+\}")
 _WHOLE_PLACEHOLDER_RE = re.compile(r"^\{[^{}]+\}$")
 
@@ -64,6 +66,59 @@ def _resolve_value(
     return _resolve_template(template, params, element)
 
 
+def _resolve_condition_leaf(
+    value: Any,
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Any:
+    """Resolve one declarative-condition operand leaf in a transaction (#114-A).
+
+    A ``{"$param": name}`` marker binds to the typed param value, or — when the
+    name is ``item.<field>`` — to the current ``forEach`` element's field; a
+    native literal is returned as-is.
+    """
+    if isinstance(value, dict) and isinstance(value.get("$param"), str):
+        return _resolve_value("{" + value["$param"] + "}", params, element)
+    return value
+
+
+def _resolve_condition_tree(
+    node: Any,
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Any:
+    """Resolve every ``{"$param"}`` marker in a serialized condition tree (#114-A).
+
+    Mirrors the runtime's resolver but element-aware, producing a tree shaped
+    like a declarative ``filter`` for :func:`compile_filter`.
+    """
+    out: Dict[str, Any] = {}
+    for key, value in node.items():
+        if key in ("and", "or"):
+            out[key] = [_resolve_condition_tree(s, params, element) for s in value]
+        elif key == "not":
+            out[key] = _resolve_condition_tree(value, params, element)
+        else:
+            ops: Dict[str, Any] = {}
+            for op, op_val in value.items():
+                if op == "between":
+                    lo, hi = op_val
+                    ops[op] = [
+                        _resolve_condition_leaf(lo, params, element),
+                        _resolve_condition_leaf(hi, params, element),
+                    ]
+                elif op == "in":
+                    ops[op] = [
+                        _resolve_condition_leaf(v, params, element) for v in op_val
+                    ]
+                elif op == "attributeExists":
+                    ops[op] = op_val
+                else:
+                    ops[op] = _resolve_condition_leaf(op_val, params, element)
+            out[key] = ops
+    return out
+
+
 def _resolve_record(
     record: Optional[Mapping[str, str]],
     params: Mapping[str, Any],
@@ -318,6 +373,35 @@ class TransactionExpander:
             target["ConditionExpression"] = f"{fn}(#ce)"
             return
         values = target.setdefault("ExpressionAttributeValues", {})
+        if kind == "expr":
+            # Declarative operator tree (issue #114-A): resolve each
+            # ``{"$param": name}`` marker against the tx params / forEach element
+            # (a ``{item.field}`` name binds from the element), then compile with
+            # the SAME ``compile_filter`` mechanics as the read-side filter. The
+            # compiled ``#f`` / ``:vf`` aliases never collide with the update
+            # ``#u`` namespace, so they merge cleanly.
+            concrete = _resolve_condition_tree(
+                condition["declarative"], params, element
+            )
+            compiled = compile_filter(concrete, self._serializer)
+            if compiled is None:
+                return
+            names.update(compiled["ExpressionAttributeNames"])
+            values.update(compiled["ExpressionAttributeValues"])
+            target["ConditionExpression"] = compiled["FilterExpression"]
+            return
+        if kind == "raw":
+            # A raw ``cond`` write condition (issue #114-B): the expression and
+            # ``#cr_*`` aliases are finished; bind each ``:crN`` value to its
+            # literal or — when a ``{"$param": name}`` marker — against the tx
+            # params / forEach element (a ``{item.field}`` name binds from the
+            # element). ``#cr_*`` / ``:cr*`` never collide with the update aliases.
+            names.update(condition["names"])
+            for alias, raw_val in condition["values"].items():
+                resolved = _resolve_condition_leaf(raw_val, params, element)
+                values[alias] = self._serializer.serialize(resolved)
+            target["ConditionExpression"] = condition["expression"]
+            return
         clauses = []
         for i, (field, tmpl) in enumerate(condition["fields"].items()):
             n = f"#e{i}"

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/graphddb_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.2.0
+Version: 0.2.2
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.2.0"
+version = "0.2.2"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"

{graphddb_runtime-0.2.0 → graphddb_runtime-0.2.2}/tests/test_unit.py

@@ -231,6 +231,54 @@ def test_update_item_builds_set_expression():
     assert plain(req["ExpressionAttributeValues"]) == {":c0": "disabled"}
 
 
+def test_update_item_rederives_affected_gsi_key():
+    # #115: setOrderStatus changes `status` (a GSI1 composing field). With
+    # `tenantId` also supplied, GSI1's composing fields {tenantId, status, orderId}
+    # are all available, so the update re-derives GSI1PK/GSI1SK in the SAME
+    # UpdateExpression — the index follows the row instead of rotting.
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt.execute_command(
+        "setOrderStatus",
+        {"orderId": "o1", "tenantId": "t1", "status": "SHIPPED"},
+    )
+    method, req = client.calls[0]
+    assert method == "update_item"
+    names = req["ExpressionAttributeNames"]
+    values = plain(req["ExpressionAttributeValues"])
+    # The status SET plus the re-derived GSI key attributes.
+    assert "status" in names.values()
+    gsi_pk_alias = next(a for a, n in names.items() if n == "GSI1PK")
+    gsi_sk_alias = next(a for a, n in names.items() if n == "GSI1SK")
+    assert f"{gsi_pk_alias} = " in req["UpdateExpression"]
+    pk_val_alias = req["UpdateExpression"].split(f"{gsi_pk_alias} = ")[1].split()[0].rstrip(",")
+    sk_val_alias = req["UpdateExpression"].split(f"{gsi_sk_alias} = ")[1].split()[0].rstrip(",")
+    assert values[pk_val_alias] == "TENANT#t1#STATUS#SHIPPED"
+    assert values[sk_val_alias] == "ORDER#o1"
+
+
+def test_update_item_throws_when_gsi_field_unavailable():
+    # #115: status alone affects GSI1 but tenantId is missing → explicit throw.
+    from graphddb_runtime.errors import GraphDDBError
+
+    client = FakeClient()
+    rt = make_runtime(client)
+    with pytest.raises(GraphDDBError, match=r"affects index 'GSI1'.*depends on 'tenantId'"):
+        rt.execute_command("setOrderStatusBad", {"orderId": "o1", "status": "SHIPPED"})
+    assert client.calls == []  # nothing written
+
+
+def test_update_item_does_not_touch_unaffected_gsi():
+    # #115 non-regression: disableUser changes `status` on a User whose GSI1 is
+    # keyed by `email` (status is NOT a composing field), so NO GSI re-derivation.
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt.execute_command("disableUser", {"userId": "alice", "status": "disabled"})
+    _method, req = client.calls[0]
+    assert "GSI1PK" not in req["ExpressionAttributeNames"].values()
+    assert req["UpdateExpression"] == "SET #c0 = :c0"
+
+
 def test_put_item_injects_key_attributes():
     client = FakeClient()
     rt = make_runtime(client)
@@ -342,6 +390,145 @@ def test_conditional_put_emits_attribute_not_exists_on_named_field():
     assert req["ExpressionAttributeNames"]["#ce"] == "PK"
 
 
+def test_conditional_expr_tree_renders_via_compile_filter():
+    """Issue #114-A: a declarative operator tree (`{ kind: expr, declarative }`)
+    resolves its `{$param}` markers (typed) and compiles to a ConditionExpression
+    with the read-side filter mechanics (`#f`/`:vf` aliases).
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["params"] = {
+        **rt._commands["addGroupMember"]["params"],
+        "role_0": {"type": "string", "required": True},
+        "role_1": {"type": "string", "required": True},
+    }
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "expr",
+        "declarative": {
+            "and": [
+                {"role": {"in": [{"$param": "role_0"}, {"$param": "role_1"}]}},
+                {"role": {"beginsWith": {"$param": "role"}}},
+            ]
+        },
+    }
+    rt.execute_command(
+        "addGroupMember",
+        {
+            "groupId": "eng",
+            "userId": "alice",
+            "role": "admin",
+            "role_0": "admin",
+            "role_1": "owner",
+        },
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == (
+        "(#f0 IN (:vf0, :vf1) AND begins_with(#f0, :vf2))"
+    )
+    assert req["ExpressionAttributeNames"]["#f0"] == "role"
+    values = plain(req["ExpressionAttributeValues"])
+    assert values[":vf0"] == "admin"
+    assert values[":vf1"] == "owner"
+    assert values[":vf2"] == "admin"
+
+
+def test_conditional_expr_numeric_comparison_keeps_type():
+    """A numeric `{$param}` operand stays numeric (serialized as N), so `gt`
+    compares numerically rather than against a stringified value.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["disableUser"]["params"] = {
+        **rt._commands["disableUser"]["params"],
+        "minVersion": {"type": "number", "required": True},
+    }
+    rt._commands["disableUser"]["condition"] = {
+        "kind": "expr",
+        "declarative": {"version": {"gt": {"$param": "minVersion"}}},
+    }
+    rt.execute_command(
+        "disableUser", {"userId": "alice", "status": "disabled", "minVersion": 3}
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == "#f0 > :vf0"
+    assert req["ExpressionAttributeValues"][":vf0"] == {"N": "3"}
+
+
+def test_conditional_expr_size_renders_size_function():
+    """Audit fix (issue #114-A): the `size` operator must compile to
+    `size(#f) = :v`, not be silently dropped. The numeric length operand stays
+    N-typed.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["params"] = {
+        **rt._commands["addGroupMember"]["params"],
+        "role_size": {"type": "number", "required": True},
+    }
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "expr",
+        "declarative": {"role": {"size": {"$param": "role_size"}}},
+    }
+    rt.execute_command(
+        "addGroupMember",
+        {"groupId": "eng", "userId": "alice", "role": "admin", "role_size": 5},
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == "size(#f0) = :vf0"
+    assert req["ExpressionAttributeNames"]["#f0"] == "role"
+    assert req["ExpressionAttributeValues"][":vf0"] == {"N": "5"}
+
+
+def test_conditional_raw_cond_literal_renders_verbatim():
+    """Issue #114-B: a raw `cond` write condition (`{ kind: raw }`) attaches its
+    pre-compiled expression + `#cr_*` names verbatim, binding each `:crN` literal
+    value (here 'banned') exactly as the TS `serializeRawCondition` emitted it.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "raw",
+        "expression": "#cr_role <> :cr0 AND attribute_exists(#cr_role)",
+        "names": {"#cr_role": "role"},
+        "values": {":cr0": "banned"},
+    }
+    rt.execute_command(
+        "addGroupMember", {"groupId": "eng", "userId": "alice", "role": "admin"}
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == (
+        "#cr_role <> :cr0 AND attribute_exists(#cr_role)"
+    )
+    assert req["ExpressionAttributeNames"]["#cr_role"] == "role"
+    assert plain(req["ExpressionAttributeValues"])[":cr0"] == "banned"
+
+
+def test_conditional_raw_cond_binds_param_marker():
+    """Issue #114-B: a `{ $param }` value marker in a raw `cond` condition binds
+    from the typed caller param (here `cond_p0`), so TS and Python compare against
+    the same bound value.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["params"] = {
+        **rt._commands["addGroupMember"]["params"],
+        "cond_p0": {"type": "string", "required": True},
+    }
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "raw",
+        "expression": "#cr_role = :cr0",
+        "names": {"#cr_role": "role"},
+        "values": {":cr0": {"$param": "cond_p0"}},
+    }
+    rt.execute_command(
+        "addGroupMember",
+        {"groupId": "eng", "userId": "alice", "role": "admin", "cond_p0": "admin"},
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == "#cr_role = :cr0"
+    assert plain(req["ExpressionAttributeValues"])[":cr0"] == "admin"
+
+
 # ── declarative transactions (issue #46) ────────────────────────────────────