modmex-lambda 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

modmex_lambda/connectors/dynamodb.py

@@ -19,53 +19,60 @@ class Connector(IDynamodbConnector):
         self.table_name = table_name
         self._client = client
         self.retry_config = retry_config
+        self._serializer = None
+        self._deserializer = None
 
     @property
     def client(self):
         if not self._client:
             import boto3
-            self._client = boto3.resource('dynamodb')
+            self._client = boto3.client('dynamodb')
         return self._client
 
     def get(self, input_params):
-        return  self.client.Table(self.table_name).get_item(
-            **input_params
+        response = self.client.get_item(
+            TableName=self.table_name,
+            **self._marshall_request(input_params),
         )
+        return self._unmarshall_response(response)
 
     def update(self, input_params):
-        return  self.client.Table(self.table_name).update_item(
-            **input_params
+        response = self.client.update_item(
+            TableName=self.table_name,
+            **self._marshall_request(input_params),
         )
+        return self._unmarshall_response(response)
 
     def put(self, input_params):
-        return  self.client.Table(self.table_name).put_item(
-            **input_params
+        response = self.client.put_item(
+            TableName=self.table_name,
+            **self._marshall_request(input_params),
         )
+        return self._unmarshall_response(response)
 
     def query(self, input_params):
-        return  self.client.Table(self.table_name).query(
-            **input_params
+        response = self.client.query(
+            TableName=self.table_name,
+            **self._marshall_request(input_params),
         )
+        return self._unmarshall_response(response)
 
     def query_page(self, input_params):
         return self.query(input_params)
 
     def scan(self, input_params):
-        return self.client.Table(self.table_name).scan(
-            **input_params
+        response = self.client.scan(
+            TableName=self.table_name,
+            **self._marshall_request(input_params),
         )
+        return self._unmarshall_response(response)
 
     def query_all(self, input_params):
         items = []
         while True:
-
-            result = self.client.Table(self.table_name).query(
-                **input_params
-            )
-            for item in result['Items']:
-                items.append(item)
-
-            if 'LastEvaluatedKey' in result and result['LastEvaluatedKey']:
+            result = self.query(input_params)
+            items.extend(result.get('Items', []))
+            if result.get('LastEvaluatedKey'):
                 input_params['ExclusiveStartKey'] = result['LastEvaluatedKey']
             else:
                 break
@@ -77,23 +84,175 @@ class Connector(IDynamodbConnector):
     def _batch_get(self, params, attempts):
         assert_max_retries(attempts, self.retry_config['max_retries'])
         wait(get_delay(self.retry_config['retry_wait'], len(attempts)))
-        resp = self.client.batch_get_item(**params)
-        if 'UnprocessedKeys' in resp and resp['UnprocessedKeys']:
+        response = self.client.batch_get_item(**self._marshall_batch_get_request(params))
+        response = self._unmarshall_response(response)
+        if response.get('UnprocessedKeys'):
             return self._batch_get(
-                unprocessed(params, resp),
-                [*attempts, resp]
+                unprocessed(params, response),
+                [*attempts, response]
             )
-        return accumulate(attempts, resp)
+        return accumulate(attempts, response)
 
     def bulk_insert(self, items: Iterable):
-        with self.client.Table(self.table_name).batch_writer() as batch:
-            for item in items:
-                batch.put_item(Item=item)
+        self._batch_write([
+            {
+                'PutRequest': {
+                    'Item': item,
+                },
+            }
+            for item in items
+        ])
 
     def bulk_delete(self, items: Iterable):
-        with self.client.Table(self.table_name).batch_writer() as batch:
-            for key in items:
-                batch.delete_item(Key=key)
+        self._batch_write([
+            {
+                'DeleteRequest': {
+                    'Key': key,
+                },
+            }
+            for key in items
+        ])
+
+    def _marshall_request(self, params):
+        return {
+            key: self._marshall_value(key, value)
+            for key, value in params.items()
+        }
+
+    def _marshall_batch_get_request(self, params):
+        return {
+            **params,
+            'RequestItems': {
+                table_name: {
+                    **request,
+                    'Keys': [
+                        self._marshall_item(key)
+                        for key in request.get('Keys', [])
+                    ],
+                }
+                for table_name, request in params.get('RequestItems', {}).items()
+            },
+        }
+
+    def _marshall_value(self, key, value):
+        if key in {'Key', 'Item', 'LastEvaluatedKey', 'ExclusiveStartKey'}:
+            return self._marshall_item(value)
+        if key == 'ExpressionAttributeValues':
+            return {
+                attr: self.serializer.serialize(attr_value)
+                for attr, attr_value in value.items()
+            }
+        return value
+
+    def _marshall_item(self, item):
+        return {
+            key: self.serializer.serialize(value)
+            for key, value in item.items()
+        }
+
+    def _unmarshall_response(self, response):
+        return {
+            key: self._unmarshall_value(key, value)
+            for key, value in response.items()
+        }
+
+    def _unmarshall_value(self, key, value):
+        if key in {'Item', 'LastEvaluatedKey'}:
+            return self._unmarshall_item(value)
+        if key == 'Items':
+            return [self._unmarshall_item(item) for item in value]
+        if key == 'Attributes':
+            return self._unmarshall_item(value)
+        if key == 'Responses':
+            return {
+                table_name: [self._unmarshall_item(item) for item in items]
+                for table_name, items in value.items()
+            }
+        if key == 'UnprocessedKeys':
+            return {
+                table_name: {
+                    **request,
+                    'Keys': [self._unmarshall_item(item) for item in request.get('Keys', [])],
+                }
+                for table_name, request in value.items()
+            }
+        return value
+
+    def _unmarshall_item(self, item):
+        return {
+            key: self.deserializer.deserialize(value)
+            for key, value in item.items()
+        }
+
+    @property
+    def serializer(self):
+        if not self._serializer:
+            self._load_dynamodb_types()
+        return self._serializer
+
+    @property
+    def deserializer(self):
+        if not self._deserializer:
+            self._load_dynamodb_types()
+        return self._deserializer
+
+    def _load_dynamodb_types(self):
+        from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
+        self._serializer = TypeSerializer()
+        self._deserializer = TypeDeserializer()
+
+    def _batch_write(self, requests):
+        for index in range(0, len(requests), 25):
+            self._batch_write_chunk(requests[index:index + 25], [])
+
+    def _batch_write_chunk(self, requests, attempts):
+        if not requests:
+            return
+        assert_max_retries(attempts, self.retry_config['max_retries'])
+        wait(get_delay(self.retry_config['retry_wait'], len(attempts)))
+        response = self.client.batch_write_item(
+            RequestItems={
+                self.table_name: [
+                    self._marshall_write_request(request)
+                    for request in requests
+                ],
+            },
+        )
+        unprocessed_items = response.get('UnprocessedItems', {}).get(self.table_name, [])
+        if unprocessed_items:
+            self._batch_write_chunk(
+                [
+                    self._unmarshall_write_request(request)
+                    for request in unprocessed_items
+                ],
+                [*attempts, response],
+            )
+
+    def _marshall_write_request(self, request):
+        if 'PutRequest' in request:
+            return {
+                'PutRequest': {
+                    'Item': self._marshall_item(request['PutRequest']['Item']),
+                },
+            }
+        return {
+            'DeleteRequest': {
+                'Key': self._marshall_item(request['DeleteRequest']['Key']),
+            },
+        }
+
+    def _unmarshall_write_request(self, request):
+        if 'PutRequest' in request:
+            return {
+                'PutRequest': {
+                    'Item': self._unmarshall_item(request['PutRequest']['Item']),
+                },
+            }
+        return {
+            'DeleteRequest': {
+                'Key': self._unmarshall_item(request['DeleteRequest']['Key']),
+            },
+        }
 
 
 def unprocessed(params, resp):

modmex_lambda/connectors/module.py

@@ -17,9 +17,12 @@ class AwsConnectorsModule(Module):
     @singleton
     @provider
     def provide_dynamodb(self) -> IDynamodbConnector:
+        import os
         from modmex_lambda.connectors.dynamodb import Connector
 
-        return Connector()
+        return Connector(
+            table_name=os.getenv('ENTITY_TABLE_NAME') or os.getenv('EVENT_TABLE_NAME'),
+        )
 
     @singleton
     @provider

modmex_lambda/persistence/__init__.py

@@ -0,0 +1,2 @@
+"""Persistence helpers for common modmex-lambda application patterns."""
+

modmex_lambda/persistence/dynamodb/__init__.py

@@ -0,0 +1,39 @@
+"""DynamoDB persistence helpers."""
+
+from modmex_lambda.persistence.dynamodb.expressions import (
+    pk_condition,
+    timestamp_condition,
+    update_expression,
+)
+from modmex_lambda.persistence.dynamodb.keys import (
+    AggregateKeyStrategy,
+    KeyStrategy,
+    SingleEntityKeyStrategy,
+    TenantPartitionKeyStrategy,
+    TenantScopedSortKeyStrategy,
+)
+from modmex_lambda.persistence.dynamodb.materialized_views import (
+    DynamoDBUpdateRequestMixin,
+    MaterializedViewMixin,
+)
+from modmex_lambda.persistence.dynamodb.stream_fields import (
+    DefaultStreamFieldsStrategy,
+    StreamFieldsStrategy,
+    stream_entity_fields,
+)
+
+__all__ = [
+    "AggregateKeyStrategy",
+    "DynamoDBUpdateRequestMixin",
+    "KeyStrategy",
+    "MaterializedViewMixin",
+    "SingleEntityKeyStrategy",
+    "DefaultStreamFieldsStrategy",
+    "StreamFieldsStrategy",
+    "TenantPartitionKeyStrategy",
+    "TenantScopedSortKeyStrategy",
+    "pk_condition",
+    "stream_entity_fields",
+    "timestamp_condition",
+    "update_expression",
+]

modmex_lambda/persistence/dynamodb/expressions.py

@@ -0,0 +1,62 @@
+from functools import reduce
+
+
+def update_expression(item: dict):
+    keys = item.keys()
+    result = {}
+    result['ExpressionAttributeNames'] = reduce(
+        lambda accumulator, el: {**accumulator, **el},
+        map(
+            lambda attrName: {f"#{attrName}": attrName },
+            keys
+        ),
+        {}
+    )
+    result['ExpressionAttributeValues'] = reduce(
+        lambda accumulator, el: {**accumulator, **el},
+        map(
+            lambda attrName: {f":{attrName}": item[attrName] },
+            filter(
+                lambda attrName: item[attrName] is not None,
+                keys
+            )
+        ),
+        {}
+    )
+    result['UpdateExpression'] = "SET "+", ".join(map(
+            lambda attrName: f"#{attrName} = :{attrName}",
+            filter(
+                lambda attrName: item[attrName] is not None,
+                keys
+            )
+        ))
+    update_expression_remove = ", ".join(map(
+            lambda attrName: f"#{attrName}",
+            filter(
+                lambda attrName: item[attrName] is None,
+                keys
+            )
+        ))
+    if update_expression_remove:
+        result['UpdateExpression'] = "{} REMOVE {}".format(
+            result['UpdateExpression'],
+            update_expression_remove
+        )
+    result['ReturnValues'] = 'ALL_NEW'
+    return result
+
+
+def timestamp_condition(field_name = 'timestamp'):
+    return {
+        'ConditionExpression': "attribute_not_exists(#{fn}) OR #{fn} < :{fn}".format(
+            fn=field_name
+        )
+    }
+
+
+def pk_condition(field_name = 'pk'):
+    return {
+        'ConditionExpression': "attribute_not_exists({})".format(
+            field_name
+        )
+    }

modmex_lambda/persistence/dynamodb/keys.py

@@ -0,0 +1,133 @@
+"""Reusable DynamoDB key strategies.
+
+These helpers keep key-shaping decisions explicit while letting repositories
+stay focused on persistence behavior.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+class KeyStrategy(ABC):
+    """Build DynamoDB primary keys for ids and entities."""
+
+    @abstractmethod
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class SingleEntityKeyStrategy(KeyStrategy):
+    """Use the entity id as pk and a fixed discriminator as sk."""
+
+    discriminator: str
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        return {
+            "pk": str(entity_id),
+            "sk": self.discriminator,
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        return self.key_for_id(_entity_attr(entity, "id"), **context)
+
+
+@dataclass(frozen=True)
+class TenantScopedSortKeyStrategy(KeyStrategy):
+    """Use entity id as pk and discriminator plus tenant id as sk."""
+
+    discriminator: str
+    separator: str = "#"
+    tenant_field: str = "tenant_id"
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_value(context, self.tenant_field)
+        return {
+            "pk": str(entity_id),
+            "sk": self._sort_key(tenant_id),
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_or_entity_value(context, entity, self.tenant_field)
+        return self.key_for_id(_entity_attr(entity, "id"), **{self.tenant_field: tenant_id})
+
+    def _sort_key(self, tenant_id: Any) -> str:
+        return f"{self.discriminator}{self.separator}{tenant_id}"
+
+
+@dataclass(frozen=True)
+class TenantPartitionKeyStrategy(KeyStrategy):
+    """Use tenant id as pk and discriminator plus entity id as sk."""
+
+    discriminator: str
+    separator: str = "#"
+    tenant_field: str = "tenant_id"
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_value(context, self.tenant_field)
+        return {
+            "pk": str(tenant_id),
+            "sk": self._sort_key(entity_id),
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_or_entity_value(context, entity, self.tenant_field)
+        return self.key_for_id(_entity_attr(entity, "id"), **{self.tenant_field: tenant_id})
+
+    def _sort_key(self, entity_id: Any) -> str:
+        return f"{self.discriminator}{self.separator}{entity_id}"
+
+
+@dataclass(frozen=True)
+class AggregateKeyStrategy(KeyStrategy):
+    """Use aggregate id as pk and entity name plus entity id as sk."""
+
+    aggregate_name: str
+    entity_name: str
+    separator: str = "#"
+    aggregate_field: str = "aggregate_id"
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        aggregate_id = _context_value(context, self.aggregate_field)
+        return {
+            "pk": f"{self.aggregate_name}{self.separator}{aggregate_id}",
+            "sk": f"{self.entity_name}{self.separator}{entity_id}",
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        aggregate_id = _context_or_entity_value(context, entity, self.aggregate_field)
+        return self.key_for_id(_entity_attr(entity, "id"), **{self.aggregate_field: aggregate_id})
+
+
+def _context_value(context: dict[str, Any], field_name: str) -> Any:
+    if field_name in context and context[field_name] is not None:
+        return context[field_name]
+    raise KeyError(f"Missing required key context: {field_name}")
+
+
+def _context_or_entity_value(context: dict[str, Any], entity: Any, field_name: str) -> Any:
+    if field_name in context and context[field_name] is not None:
+        return context[field_name]
+    value = _entity_attr(entity, field_name)
+    if value is not None:
+        return value
+    raise AttributeError(f"Entity is missing required field: {field_name}")
+
+
+def _entity_attr(entity: Any, field_name: str) -> Any:
+    if isinstance(entity, dict):
+        try:
+            return entity[field_name]
+        except KeyError as exc:
+            raise AttributeError(f"Entity is missing required field: {field_name}") from exc
+    try:
+        return getattr(entity, field_name)
+    except AttributeError as exc:
+        raise AttributeError(f"Entity is missing required field: {field_name}") from exc

modmex_lambda/persistence/dynamodb/materialized_views.py

@@ -0,0 +1,80 @@
+"""DynamoDB helpers for materialized view update requests."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from modmex_lambda.persistence.dynamodb.expressions import timestamp_condition, update_expression
+from modmex_lambda.persistence.dynamodb.stream_fields import stream_entity_fields
+from modmex_lambda.stream.utils.time import ttl as stream_ttl
+
+
+class DynamoDBUpdateRequestMixin:
+    """Build DynamoDB UpdateItem requests with a timestamp guard by default."""
+
+    def build_update_request(
+        self,
+        *,
+        key: dict[str, Any],
+        fields: dict[str, Any],
+        timestamp_condition_enabled: bool = True,
+    ) -> dict[str, Any]:
+        request = {
+            "Key": key,
+            **update_expression(fields),
+        }
+
+        if timestamp_condition_enabled:
+            request.update(timestamp_condition())
+
+        return request
+
+
+class MaterializedViewMixin(DynamoDBUpdateRequestMixin):
+    """Map stream unit-of-work events into DynamoDB materialized view updates."""
+
+    discriminator: str
+    materialized_source_name: str | None = None
+    materialized_last_modified_by: str | None = "system"
+    use_ttl: bool = False
+    days_ttl: int = 30
+
+    @classmethod
+    def materialized_update_request_mapper(cls) -> Callable[[dict[str, Any]], dict[str, Any]]:
+        materializer = cls.__new__(cls)
+        return materializer.to_materialized_update_request
+
+    def to_materialized_update_request(self, uow: dict[str, Any]) -> dict[str, Any]:
+        entity_name = self.materialized_source_name or self.discriminator
+        entity = uow["event"][entity_name]
+
+        return self.build_update_request(
+            key=self.materialized_key(uow, entity),
+            fields=self.materialized_fields(uow, entity),
+        )
+
+    def materialized_key(self, uow: dict[str, Any], entity: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "pk": entity["id"],
+            "sk": entity.get("sk", self.discriminator),
+        }
+
+    def materialized_fields(self, uow: dict[str, Any], entity: dict[str, Any]) -> dict[str, Any]:
+        timestamp = uow["event"]["timestamp"]
+        source_name = self.materialized_source_name or self.discriminator
+        fields = {
+            **{key: value for key, value in entity.items() if key not in ["pk", "sk"]},
+            **stream_entity_fields(
+                self.discriminator,
+                timestamp=timestamp,
+                deleted=True if uow["event"]["type"] == f"{source_name}-deleted" else None,
+                latched=True,
+                ttl=stream_ttl(timestamp, self.days_ttl) if self.use_ttl else None,
+            ),
+        }
+        if self.materialized_last_modified_by is not None:
+            fields["last_modified_by"] = self.materialized_last_modified_by
+        return fields
+
+
+__all__ = ["DynamoDBUpdateRequestMixin", "MaterializedViewMixin"]

modmex_lambda/persistence/dynamodb/stream_fields.py

@@ -0,0 +1,121 @@
+"""Fields used by modmex-lambda stream-compatible DynamoDB items."""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from modmex_lambda.stream.utils.time import now, ttl as stream_ttl
+
+
+def stream_entity_fields(
+    discriminator: str,
+    *,
+    timestamp: int,
+    deleted: bool | None = None,
+    latched: bool = False,
+    ttl: int | None = None,
+    awsregion: str | None = None,
+) -> dict[str, Any]:
+    """Build standard fields consumed by modmex-lambda stream processors."""
+
+    fields = {
+        "discriminator": discriminator,
+        "deleted": deleted,
+        "latched": latched,
+        "ttl": ttl,
+        "awsregion": awsregion if awsregion is not None else os.getenv("REGION"),
+        "timestamp": timestamp,
+    }
+    return fields
+
+
+class StreamFieldsStrategy(ABC):
+    """Build stream-compatible item fields for DynamoDB writes."""
+
+    @abstractmethod
+    def fields_for_save(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def fields_for_delete(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class DefaultStreamFieldsStrategy(StreamFieldsStrategy):
+    """Default stream field contract used by modmex-lambda stream processors."""
+
+    discriminator: str
+    key_fields: tuple[str, ...] = field(default=("pk", "sk"))
+    use_ttl: bool = False
+    days_ttl: int = 30
+
+    def fields_for_save(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        timestamp = self._timestamp(timestamp)
+        return {
+            **self._without_key_fields(data),
+            **stream_entity_fields(
+                self.discriminator,
+                timestamp=timestamp,
+                deleted=None,
+                latched=False,
+                ttl=self._ttl(timestamp, ttl),
+            ),
+        }
+
+    def fields_for_delete(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        timestamp = self._timestamp(timestamp)
+        return {
+            **self._without_key_fields(data),
+            **stream_entity_fields(
+                self.discriminator,
+                timestamp=timestamp,
+                deleted=True,
+                latched=False,
+                ttl=self._ttl(timestamp, ttl),
+            ),
+        }
+
+    def _without_key_fields(self, data: dict[str, Any]) -> dict[str, Any]:
+        return {
+            key: value
+            for key, value in data.items()
+            if key not in self.key_fields
+        }
+
+    def _timestamp(self, timestamp: int | None) -> int:
+        return timestamp if timestamp is not None else now()
+
+    def _ttl(self, timestamp: int, ttl: int | None) -> int | None:
+        if ttl is not None:
+            return ttl
+        if self.use_ttl:
+            return stream_ttl(timestamp, self.days_ttl)
+        return None

modmex_lambda/stream/utils/dynamodb.py

@@ -1,8 +1,12 @@
 import os
 from typing import Union
-from functools import reduce
 from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
 from modmex_lambda.connectors.dynamodb import Connector
+from modmex_lambda.persistence.dynamodb.expressions import (
+    pk_condition,
+    timestamp_condition,
+    update_expression,
+)
 from modmex_lambda.stream.operators.dynamodb import (
     BatchGetDynamoDB,
     PutDynamoDB,
@@ -20,65 +24,6 @@ def serialize_number(number: str) -> Union[float, int]:
 
 setattr(TypeDeserializer, '_deserialize_n', lambda _, number: serialize_number(number))
 
-
-def update_expression(item: dict):
-    keys = item.keys()
-    result = {}
-    result['ExpressionAttributeNames'] = reduce(
-        lambda accumulator, el: {**accumulator, **el},
-        map(
-            lambda attrName: {f"#{attrName}": attrName },
-            keys
-        ),
-        {}
-    )
-    result['ExpressionAttributeValues'] = reduce(
-        lambda accumulator, el: {**accumulator, **el},
-        map(
-            lambda attrName: {f":{attrName}": item[attrName] },
-            filter(
-                lambda attrName: item[attrName] is not None,
-                keys
-            )
-        ),
-        {}
-    )
-    result['UpdateExpression'] = "SET "+", ".join(map(
-            lambda attrName: f"#{attrName} = :{attrName}",
-            filter(
-                lambda attrName: item[attrName] is not None,
-                keys
-            )
-        ))
-    update_expression_remove = ", ".join(map(
-            lambda attrName: f"#{attrName}",
-            filter(
-                lambda attrName: item[attrName] is None,
-                keys
-            )
-        ))
-    if update_expression_remove:
-        result['UpdateExpression'] = "{} REMOVE {}".format(
-            result['UpdateExpression'],
-            update_expression_remove
-        )
-    result['ReturnValues'] = 'ALL_NEW'
-    return result
-
-def timestamp_condition(field_name = 'timestamp'):
-    return {
-        'ConditionExpression': "attribute_not_exists(#{fn}) OR #{fn} < :{fn}".format(
-            fn=field_name
-        )
-    }
-
-def pk_condition(field_name = 'pk'):
-    return {
-        'ConditionExpression': "attribute_not_exists({})".format(
-            field_name
-        )
-    }
-
 def update_dynamodb(
     table_name=os.getenv('ENTITY_TABLE_NAME') or os.getenv('EVENT_TABLE_NAME'),
     update_request_field='update_request',

{modmex_lambda-0.5.2.dist-info → modmex_lambda-0.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modmex-lambda
-Version: 0.5.2
+Version: 0.5.4
 Summary: Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling.
 Author: Modmex
 License: MIT
@@ -36,6 +36,8 @@ API Gateway proxy events, fast routing, request binding, response serialization,
 middleware, dependency injection, stream sources, parsing, and structured
 logging.
 
+The fuller documentation site lives in [`docs/`](docs/).
+
 ## Install
 
 ```bash
@@ -979,37 +981,66 @@ materialize so queries stay local and fast, and each service owns the model it
 needs instead of querying another service synchronously.
 
 ```python
+from modmex_lambda.persistence.dynamodb import MaterializedViewMixin
 from modmex_lambda.stream.flavors.materialize import Materialize
 from modmex_lambda.stream.rules_registry import RulesRegistry
 from modmex_lambda.stream.sources import KinesisSource
-from modmex_lambda.stream.utils.dynamodb import update_expression
 
 
-def to_thing_view_update(uow):
-    thing = uow["event"]["thing"]
-    return {
-        "Key": {
-            "pk": thing["id"],
-            "sk": "THING",
-        },
-        **update_expression({
-            "name": thing["name"],
-            "timestamp": uow["event"]["timestamp"],
-        }),
-    }
+class ThingViewRepository(MaterializedViewMixin):
+    discriminator = "thing"
+
+
+to_update_request = ThingViewRepository.materialized_update_request_mapper()
 
 
 registry = RulesRegistry().registry(
     Materialize({
         "id": "materialize-thing",
         "event_type": "thing-created",
-        "to_update_request": to_thing_view_update,
+        "to_update_request": to_update_request,
     })
 )
 
 handler = KinesisSource(registry, concurrency=False).handle
 ```
 
+`MaterializedViewMixin` is a persistence helper for the common DynamoDB case:
+copy the entity from `uow["event"][discriminator]`, build a `Key` with
+`pk=entity["id"]` and `sk=discriminator`, add stream-compatible fields, and
+protect the write with `timestamp_condition()` so older events do not overwrite
+newer records. It adds stream-compatible fields such as `discriminator`,
+`timestamp`, `deleted`, `latched`, `ttl`, and `awsregion` to the update
+expression.
+
+Override the hooks when the event source, key, projection, or enrichment is
+different from the default:
+
+```python
+from modmex_lambda.persistence.dynamodb import MaterializedViewMixin
+
+
+class ThingSearchViewRepository(MaterializedViewMixin):
+    discriminator = "thing-search"
+    materialized_source_name = "thing"
+
+    def materialized_key(self, uow, thing):
+        return {
+            "pk": thing["tenant_id"],
+            "sk": f"thing-search#{thing['id']}",
+        }
+
+    def materialized_fields(self, uow, thing):
+        return {
+            **super().materialized_fields(uow, thing),
+            "search_text": f"{thing['name']} {thing['tenant_id']}",
+        }
+```
+
+Use `DynamoDBUpdateRequestMixin.build_update_request()` directly when you already
+have the key and fields but still want the standard `UpdateItem` expression and
+timestamp guard.
+
 Use `split_on` and `split_target_field` when one event updates several records,
 for example one `order-created` event materializing each order item.
 

{modmex_lambda-0.5.2.dist-info → modmex_lambda-0.5.4.dist-info}/RECORD

@@ -13,7 +13,7 @@ modmex_lambda/tracing.py,sha256=WWA2xAqfa23phxoQzRnr6UtdK3S770jPODYh4CwFk0M,5739
 modmex_lambda/validation.py,sha256=64uWzSnkxzN1t7DAqC_0TYzhupQUtAWnrLATEFAEfzs,7130
 modmex_lambda/connectors/__init__.py,sha256=-3G8Q5Qo_O6xlD8oWLYW7XCgMln50BTjhrUncAePnUA,716
 modmex_lambda/connectors/cloudwatch.py,sha256=8NnP6m7IGZwwFZaHw6EO2Q1g4yHUfFqagpkVpzlgW8E,455
-modmex_lambda/connectors/dynamodb.py,sha256=uSK7mBKORigcx_BtiLpxob3dBxRTpWkCcdMCgPRclNQ,3575
+modmex_lambda/connectors/dynamodb.py,sha256=QTUtud8pmsmPER2N0foQB9dBg3yCrfEacYk8FfU1XfQ,8821
 modmex_lambda/connectors/eventbridge.py,sha256=atY6R4XqRL-n6y5-ajn3b-t0gDwaBvz1w5rU4yMmq1U,473
 modmex_lambda/connectors/icloudwatch.py,sha256=LAxYgMgzda4wtGGRwhsPlZikpGlA3oiUsk73jlJ7ghk,463
 modmex_lambda/connectors/idynamodb.py,sha256=oZiOztqY59U9O5VpxsAG_b1H2L4VaMH0lWhGGapHfYo,2538
@@ -23,7 +23,7 @@ modmex_lambda/connectors/is3.py,sha256=o3NCwCUqyK7vchSBVusVxhnTjaWaej1TaCmAKiwFA
 modmex_lambda/connectors/isns.py,sha256=7EgdIUuVC1V0wsdNaZthdepRDZkpw6XBUUzWr6C8NW8,717
 modmex_lambda/connectors/isqs.py,sha256=qd-MPGuJKeKFJ3wK-RvvPCl_f0x6NC9n8GRsiqI5krQ,706
 modmex_lambda/connectors/lambda_.py,sha256=kHpQxGSX-5tAtSZlI0VdR3WLP9KCCPIjcnACqTI9vqE,421
-modmex_lambda/connectors/module.py,sha256=BTAEK9LBaQ7YIFP6lSzQuoHW3yV4tsQlznIqHj74Iuc,1852
+modmex_lambda/connectors/module.py,sha256=u1wLIt7JF7ncCJA8qX5tTwhJ906u-XnE84B8CzM7yxc,1967
 modmex_lambda/connectors/s3.py,sha256=sEf4_xV-kQXkOTIwo_Ez9RJxmJWDzRu0mLe0SLjY8-I,1135
 modmex_lambda/connectors/sns.py,sha256=1X_5laGHTtyOH5gXqhDWk9YnclHzEac1R76xaijZQ_U,879
 modmex_lambda/connectors/sqs.py,sha256=LwzO3gkQ6bfE6WMJW1KrhsymUqtdZ94RK1suXL7G-k0,806
@@ -55,6 +55,12 @@ modmex_lambda/event_handler/dependencies/dependency_middleware.py,sha256=c_N7Ugt
 modmex_lambda/event_handler/dependencies/depends.py,sha256=pJ1rcMoA99vSaQTPxJ0zkYppPDKU0-lm9URc9Gifmdw,7110
 modmex_lambda/event_handler/dependencies/params.py,sha256=bc208GHiXCfm1V-GLeIMm8-ypZ8P8Q9qUKQkK2Vh1Fg,10085
 modmex_lambda/event_handler/dependencies/types.py,sha256=5VA8zl-EjQDNKXOrNT7sRv_vNs40Lz8aMP-sf-lf8sk,376
+modmex_lambda/persistence/__init__.py,sha256=oa4FHCvitEkoagJ059jGATj6GSm-maazzf_QNi4WdQs,74
+modmex_lambda/persistence/dynamodb/__init__.py,sha256=f_R3NHWfHvTWkCYfBHqY-z75r7pESsUv5FmFf05Glgg,1026
+modmex_lambda/persistence/dynamodb/expressions.py,sha256=E_FDebLgROv63DBRQXKuO1hXjTt9g1kGzbgH2YBNu-Y,1694
+modmex_lambda/persistence/dynamodb/keys.py,sha256=_vjpHYzRmi1OmCzHaJNpq8vefjH7kq8yxE1t7RhmmQg,4676
+modmex_lambda/persistence/dynamodb/materialized_views.py,sha256=CnSWZMYkEHGEpTnWkurB2uxxTN_tPrGFgRthF_0ILng,2892
+modmex_lambda/persistence/dynamodb/stream_fields.py,sha256=b6wRRq6Ag9W59GCI8616IlBQXeBIwj5RKEQE0lfD4YE,3323
 modmex_lambda/shared/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 modmex_lambda/shared/cookies.py,sha256=E2hTuht5_Xljw9zOQLW6vjsOWEpQSIqD2D3Tl1Co_s0,2076
 modmex_lambda/shared/headers_serializer.py,sha256=Ao-wpx0cmy9E2ACrh7R7RIDUF0h24gax1AMtY_MjIWQ,2505
@@ -113,7 +119,7 @@ modmex_lambda/stream/utils/cloudwatch.py,sha256=B9y-Ab5EaZeso5ph3RxRaK8tU-mQyEvA
 modmex_lambda/stream/utils/concurrency.py,sha256=7fHyQF4SkOkcao8XmG6UOJQersJhf0n5kauk9Yr_-F0,1336
 modmex_lambda/stream/utils/contracts.py,sha256=SpGX4JGukHmeb1y2ChahuNUrHtHA_rA61VXz_13VvbU,931
 modmex_lambda/stream/utils/decorators.py,sha256=-Z1ebvN2m07-lfiEkgRPTEZDL9OI6GSI3w7LWq2Xn88,163
-modmex_lambda/stream/utils/dynamodb.py,sha256=PeY8jXutQmQXKLey6TBGFsnua18vZm2-NVFG7UhblqI,4233
+modmex_lambda/stream/utils/dynamodb.py,sha256=vi9OEU9DJDzxFdwQkObk-kuZrT0Z1DFOmMrs4eUoXZ8,2670
 modmex_lambda/stream/utils/eventbridge.py,sha256=_3Oe6eHFdBBuE-9XowGjPbXxQb60N3v-47ieBWp7tv0,745
 modmex_lambda/stream/utils/faults.py,sha256=iXIzzSOHIW-kW4J2PKW_v1KviFpao2btvSrnRUer-d4,2660
 modmex_lambda/stream/utils/filters.py,sha256=8OmVfHt_xmczgZYyq6OkwEByMg5kQKioPQKA0le1CbY,433
@@ -132,7 +138,7 @@ modmex_lambda/stream/utils/time.py,sha256=dnsL2xeWpa1FXm2p8y9rWXtICMBlCBkgLaJ_en
 modmex_lambda/stream/utils/uow.py,sha256=8WSPVE7AiHInkFDfBEeKOvdirY6GAgBoS7qkF1f1JVM,3207
 modmex_lambda/stream/utils/data_classes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 modmex_lambda/stream/utils/data_classes/dynamodb.py,sha256=h_7MtUyRkvvV1r2QECrRDu7RR4Hh94SwSjc_8K2_XGM,363
-modmex_lambda-0.5.2.dist-info/METADATA,sha256=s5iPsfZFyFDYMZLUn7LpP5py9ePfax9KcHevPN5AyFw,31809
-modmex_lambda-0.5.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-modmex_lambda-0.5.2.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
-modmex_lambda-0.5.2.dist-info/RECORD,,
+modmex_lambda-0.5.4.dist-info/METADATA,sha256=Vt6fiHLcaMqIv2D8dAYERIo2891Az0v_GFLDN_Q0Y5k,33046
+modmex_lambda-0.5.4.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modmex_lambda-0.5.4.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
+modmex_lambda-0.5.4.dist-info/RECORD,,