lightspeed/data_ergonomics

ORM/data ergonomics parity profile contracts for M57.

Types

Changeset

Nested changeset used by CRUD/forms workflows.

pub type Changeset {
  Changeset(
    resource: String,
    fields: List(Field),
    nested: List(Changeset),
    errors: List(String),
  )
}

Constructors

Changeset(
  resource: String,
  fields: List(Field),
  nested: List(Changeset),
  errors: List(String),
)

DashboardSummary

Dashboard summary for common status cards.

pub type DashboardSummary {
  DashboardSummary(
    total_rows: Int,
    draft_rows: Int,
    published_rows: Int,
    stale_rows: Int,
  )
}

Constructors

DashboardSummary(
  total_rows: Int,
  draft_rows: Int,
  published_rows: Int,
  stale_rows: Int,
)

DataError

Typed data errors for CRUD and concurrency flows.

pub type DataError {
  ValidationFailed(String)
  NotFound(String)
  ConcurrencyConflict(id: String, expected: Int, actual: Int)
}

Constructors

```
ValidationFailed(String)
```
```
NotFound(String)
```

ConcurrencyConflict(id: String, expected: Int, actual: Int)

Field

One mapped field in a changeset.

pub type Field {
  Field(
    name: String,
    value: FieldValue,
    rules: List(ValidationRule),
    errors: List(String),
  )
}

Constructors

Field(
  name: String,
  value: FieldValue,
  rules: List(ValidationRule),
  errors: List(String),
)

FieldValue

Typed field value for changeset input mapping.

pub type FieldValue {
  TextValue(String)
  IntValue(Int)
  BoolValue(Bool)
  EmptyValue
}

Constructors

```
TextValue(String)
```
```
IntValue(Int)
```
```
BoolValue(Bool)
```
```
EmptyValue
```

QueryDiagnostic

Query diagnostic event.

pub type QueryDiagnostic {
  NPlusOneDetected(query: String, statement_count: Int)
  SlowQueryDetected(query: String, latency_ms: Int)
  TraceCorrelated(trace_id: String, query: String)
}

Constructors

NPlusOneDetected(query: String, statement_count: Int)

SlowQueryDetected(query: String, latency_ms: Int)

TraceCorrelated(trace_id: String, query: String)

QueryShape

Query shape used for diagnostics.

pub type QueryShape {
  QueryShape(
    name: String,
    projected_rows: Int,
    statement_count: Int,
    estimated_latency_ms: Int,
    trace_id: String,
  )
}

Constructors

QueryShape(
  name: String,
  projected_rows: Int,
  statement_count: Int,
  estimated_latency_ms: Int,
  trace_id: String,
)

Row

One persisted row.

pub type Row {
  Row(
    id: String,
    revision: Int,
    resource: String,
    attributes: List(#(String, String)),
  )
}

Constructors

Row(
  id: String,
  revision: Int,
  resource: String,
  attributes: List(#(String, String)),
)

Runtime

opaque

Deterministic runtime storage.

pub opaque type Runtime

UnitOfWork

Unit-of-work contract.

pub type UnitOfWork {
  UnitOfWork(name: String, operations: List(UnitOperation))
}

Constructors

UnitOfWork(name: String, operations: List(UnitOperation))

UnitOfWorkError

Unit-of-work failure with operation index.

pub type UnitOfWorkError {
  OperationFailed(index: Int, error: DataError)
}

Constructors

OperationFailed(index: Int, error: DataError)

UnitOperation

One transaction operation.

pub type UnitOperation {
  CreateFromChangeset(changeset: Changeset)
  UpdateFromChangeset(
    id: String,
    expected_revision: Int,
    changeset: Changeset,
  )
  DeleteById(id: String)
}

Constructors

CreateFromChangeset(changeset: Changeset)

UpdateFromChangeset(
  id: String,
  expected_revision: Int,
  changeset: Changeset,
)

```
DeleteById(id: String)
```

ValidationRule

Validation rule for one mapped field.

pub type ValidationRule {
  Required
  MinLength(Int)
  MinInt(Int)
}

Constructors

```
Required
```
```
MinLength(Int)
```
```
MinInt(Int)
```

Values

bool_field

pub fn bool_field(
  name: String,
  value: Bool,
  rules: List(ValidationRule),
) -> Field

Build one bool field.

changeset

pub fn changeset(
  resource: String,
  fields: List(Field),
  nested: List(Changeset),
) -> Changeset

Build one changeset.

changeset_error_signature

pub fn changeset_error_signature(changeset: Changeset) -> String

Stable changeset error signature.

changeset_errors

pub fn changeset_errors(changeset: Changeset) -> List(String)

All errors on one validated changeset.

changeset_valid

pub fn changeset_valid(changeset: Changeset) -> Bool

True when a validated changeset has no errors.

create

pub fn create(
  runtime: Runtime,
  changeset: Changeset,
) -> Result(#(Runtime, Row), DataError)

Create one row from a changeset.

dashboard_signature

pub fn dashboard_signature(summary: DashboardSummary) -> String

Stable dashboard summary signature.

dashboard_summary

pub fn dashboard_summary(runtime: Runtime) -> DashboardSummary

Build dashboard summary for common CRUD status cards.

dashboard_with_diagnostics

pub fn dashboard_with_diagnostics(
  runtime: Runtime,
  shape: QueryShape,
) -> #(DashboardSummary, List(QueryDiagnostic))

Dashboard summary with query diagnostics.

data_error_label

pub fn data_error_label(error: DataError) -> String

Stable data error label.

delete

pub fn delete(
  runtime: Runtime,
  id: String,
) -> Result(Runtime, DataError)

Delete one row.

diagnose_query

pub fn diagnose_query(shape: QueryShape) -> List(QueryDiagnostic)

Derive deterministic diagnostics for a query shape.

diagnostic_label

pub fn diagnostic_label(diagnostic: QueryDiagnostic) -> String

Stable query diagnostic label.

diagnostics_signature

pub fn diagnostics_signature(
  diagnostics: List(QueryDiagnostic),
) -> String

Stable query diagnostics signature.

empty_field

pub fn empty_field(
  name: String,
  rules: List(ValidationRule),
) -> Field

Build one empty field for required validation paths.

fetch

pub fn fetch(
  runtime: Runtime,
  id: String,
) -> Result(Row, DataError)

Fetch one row by id.

field_value_label

pub fn field_value_label(value: FieldValue) -> String

Stable field value label.

int_field

pub fn int_field(
  name: String,
  value: Int,
  rules: List(ValidationRule),
) -> Field

Build one int field.

new_runtime

pub fn new_runtime() -> Runtime

Build an empty runtime.

operation_label

pub fn operation_label(operation: UnitOperation) -> String

Stable operation label.

query_shape

pub fn query_shape(
  name: String,
  projected_rows: Int,
  statement_count: Int,
  estimated_latency_ms: Int,
  trace_id: String,
) -> QueryShape

Build one query shape.

row

pub fn row(
  id: String,
  revision: Int,
  resource: String,
  attributes: List(#(String, String)),
) -> Row

Build one row record.

row_signature

pub fn row_signature(row: Row) -> String

Stable row signature.

rows

pub fn rows(runtime: Runtime) -> List(Row)

Runtime rows in stable order.

run_unit_of_work

pub fn run_unit_of_work(
  runtime: Runtime,
  unit_of_work: UnitOfWork,
) -> Result(#(Runtime, List(String)), UnitOfWorkError)

Apply one unit-of-work with atomic semantics.

runtime_signature

pub fn runtime_signature(runtime: Runtime) -> String

Stable runtime signature for fixtures.

seed_runtime

pub fn seed_runtime(rows: List(Row)) -> Runtime

Build a runtime from existing rows.

text_field

pub fn text_field(
  name: String,
  value: String,
  rules: List(ValidationRule),
) -> Field

Build one text field.

unit_of_work

pub fn unit_of_work(
  name: String,
  operations: List(UnitOperation),
) -> UnitOfWork

Build one unit-of-work from typed operations.

unit_of_work_error_label

pub fn unit_of_work_error_label(error: UnitOfWorkError) -> String

Stable unit-of-work error label.

update

pub fn update(
  runtime: Runtime,
  id: String,
  expected_revision: Int,
  changeset: Changeset,
) -> Result(#(Runtime, Row), DataError)

Update one row with optimistic-concurrency checks.

validate_changeset

pub fn validate_changeset(changeset: Changeset) -> Changeset

Validate one changeset recursively and propagate nested errors.