tabletheory

package module
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 23, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

README

TableTheory — Multi-language DynamoDB ORM (Go, TypeScript, Python)

TableTheory is a DynamoDB-first ORM + schema contract designed to keep data access consistent across languages and reliable in generative coding workflows (humans + AI assistants).

This repo ships SDKs for:

  • Go (root): github.com/theory-cloud/tabletheory
  • TypeScript (Node.js 24): ts/ (@theory-cloud/tabletheory-ts)
  • Python (3.14): py/ (tabletheory-py / theorydb_py)

Start at docs/README.md for the documentation index.

Why TableTheory?

Use TableTheory when you want DynamoDB-backed systems that are:

  • Serverless-first: patterns that work well in AWS Lambda, including batching, transactions, streams, and optional encryption.
  • Cross-language consistent: one table, multiple services, multiple runtimes — without schema and behavior drift.
  • Generative-coding friendly: explicit schema, canonical patterns, and strict verification so AI-generated code stays correct and maintainable.

✅ CORRECT: treat schema + semantics as a contract
❌ INCORRECT: redefine “the same” table shape independently per service/language

Repository layout

  • docs/ — repo documentation (Go + multi-language pointers)
  • ts/ — TypeScript SDK + docs (ts/docs)
  • py/ — Python SDK + docs (py/docs)
  • contract-tests/ — cross-language contract fixtures + runners
  • examples/cdk-multilang/ — deployable demo: one DynamoDB table + three Lambdas (Go, Node.js 24, Python 3.14)

Getting started

Serverless data demo (CDK)

If you want a concrete “one table, three languages” deployment, start with the CDK demo: examples/cdk-multilang/README.md.

It deploys one DynamoDB table and three Lambda Function URLs (Go, Node.js 24, Python 3.14) that read/write the same item shape and exercise portability-sensitive features (encryption, batching, transactions).

For infrastructure patterns, see docs/cdk/README.md.

DMS-first workflow (language-neutral schema)

TableTheory’s drift-prevention story centers on a shared, language-neutral schema document: TableTheory Spec (DMS).

DMS (v0.1) shape (example):

dms_version: "0.1"
models:
  - name: "Note"
    table: { name: "notes_contract" }
    keys:
      partition: { attribute: "PK", type: "S" }
      sort:      { attribute: "SK", type: "S" }
    attributes:
      - { attribute: "PK", type: "S", required: true, roles: ["pk"] }
      - { attribute: "SK", type: "S", required: true, roles: ["sk"] }
      - { attribute: "value", type: "N" }

See docs/development/planning/theorydb-spec-dms-v0.1.md for the current draft semantics and portability rules.

Installation and Versioning

This repo uses GitHub Releases as the source of truth. (No npm/PyPI publishing.)

Development & verification

  • Run repo verification: make rubric
  • Run DynamoDB Local: make docker-up
  • Run full suite (includes integration): make test

More docs

Documentation

Overview

Package tabletheory provides a type-safe ORM for Amazon DynamoDB in Go.

Import path: 

import "github.com/theory-cloud/tabletheory"

Implementation lives in `internal/theorydb` so the repo root stays minimal.

Index

Constants

This section is empty.

Variables

View Source 
var (
	WithBackupTable = schema.WithBackupTable
	WithDataCopy    = schema.WithDataCopy
	WithTargetModel = schema.WithTargetModel
	WithTransform   = schema.WithTransform
	WithBatchSize   = schema.WithBatchSize
)

Re-export AutoMigrate options for convenience.

Functions

func AtVersion 

func AtVersion(version int64) core.TransactCondition

func Condition 

func Condition(field, operator string, value any) core.TransactCondition

func ConditionExpression 

func ConditionExpression(expression string, values map[string]any) core.TransactCondition

func ConditionVersion 

func ConditionVersion(version int64) core.TransactCondition

func DefaultBatchGetOptions 

func DefaultBatchGetOptions() *core.BatchGetOptions

func EnableXRayTracing 

func EnableXRayTracing() bool

func GetLambdaMemoryMB 

func GetLambdaMemoryMB() int

func GetPartnerFromContext 

func GetPartnerFromContext(ctx context.Context) string

func GetRemainingTimeMillis 

func GetRemainingTimeMillis(ctx context.Context) int64

func IfExists 

func IfExists() core.TransactCondition

func IfNotExists 

func IfNotExists() core.TransactCondition

func IsLambdaEnvironment 

func IsLambdaEnvironment() bool

func New 

func New(config session.Config) (core.ExtendedDB, error)

func NewBasic 

func NewBasic(config session.Config) (core.DB, error)

func NewKeyPair 

func NewKeyPair(partitionKey any, sortKey ...any) core.KeyPair

func PartnerContext 

func PartnerContext(ctx context.Context, partnerID string) context.Context

func UnmarshalItem 

func UnmarshalItem(item map[string]types.AttributeValue, dest interface{}) error

func UnmarshalItems 

func UnmarshalItems(items []map[string]types.AttributeValue, dest interface{}) error

func UnmarshalStreamImage 

func UnmarshalStreamImage(streamImage map[string]events.DynamoDBAttributeValue, dest interface{}) error

Types

type AccountConfig 

type AccountConfig = internaltheorydb.AccountConfig

type AutoMigrateOption 

type AutoMigrateOption = schema.AutoMigrateOption

type BatchGetOptions 

type BatchGetOptions = core.BatchGetOptions

type ColdStartMetrics 

type ColdStartMetrics = internaltheorydb.ColdStartMetrics

func BenchmarkColdStart 

func BenchmarkColdStart(models ...any) ColdStartMetrics

type Config 

type Config = session.Config

Re-export types for convenience.

type DB 

type DB = internaltheorydb.DB

type KeyPair 

type KeyPair = core.KeyPair

type LambdaDB 

type LambdaDB = internaltheorydb.LambdaDB

func LambdaInit 

func LambdaInit(models ...any) (*LambdaDB, error)

func NewLambdaOptimized 

func NewLambdaOptimized() (*LambdaDB, error)

type LambdaMemoryStats 

type LambdaMemoryStats = internaltheorydb.LambdaMemoryStats

type MultiAccountDB 

type MultiAccountDB = internaltheorydb.MultiAccountDB

func NewMultiAccount 

func NewMultiAccount(accounts map[string]AccountConfig) (*MultiAccountDB, error)

Source Files

View all Source files

Directories

Path Synopsis
Package examples demonstrates TableTheory's embedded struct support
 Package examples demonstrates TableTheory's embedded struct support
blog/handlers
blog/models
blog/services
cdk-multilang/lambdas/go command
cdk-multilang/lambdas/go/demo
encryption command
initialization command
Package main demonstrates proper TableTheory initialization patterns to avoid nil pointer dereference errors
 Package main demonstrates proper TableTheory initialization patterns to avoid nil pointer dereference errors
lambda command
optimization command
payment
payment/lambda/process command
payment/lambda/query command
payment/lambda/reconcile command
payment/utils
internal
encryption
expr
numutil
reflectutil
theorydb
lambda.go
 lambda.go
pkg
consistency
Package consistency provides utilities for handling eventual consistency in DynamoDB
 Package consistency provides utilities for handling eventual consistency in DynamoDB
core
Package core defines the core interfaces and types for TableTheory
 Package core defines the core interfaces and types for TableTheory
dms
errors
Package errors defines error types and utilities for TableTheory
 Package errors defines error types and utilities for TableTheory
index
interfaces
Package interfaces provides abstractions for AWS SDK operations to enable mocking
 Package interfaces provides abstractions for AWS SDK operations to enable mocking
lease
Package lease provides a small, correctness-first DynamoDB lease/lock helper.
 Package lease provides a small, correctness-first DynamoDB lease/lock helper.
marshal
Package marshal provides optimized marshaling for DynamoDB
 Package marshal provides optimized marshaling for DynamoDB
mocks
Package mocks provides mock implementations for TableTheory interfaces and AWS SDK operations
 Package mocks provides mock implementations for TableTheory interfaces and AWS SDK operations
model
Package model provides model registration and metadata management for TableTheory
 Package model provides model registration and metadata management for TableTheory
naming
protection
query
Package query provides aggregate functionality for DynamoDB queries
 Package query provides aggregate functionality for DynamoDB queries
schema
session
Package session provides AWS session management and DynamoDB client configuration
 Package session provides AWS session management and DynamoDB client configuration
testing
Package testing provides utilities for testing applications that use TableTheory.
 Package testing provides utilities for testing applications that use TableTheory.
transaction
Package transaction provides atomic transaction support for TableTheory
 Package transaction provides atomic transaction support for TableTheory
types
Package types provides type conversion between Go types and DynamoDB AttributeValues
 Package types provides type conversion between Go types and DynamoDB AttributeValues
validation
scripts
internal/dms_first_workflow command
internal/expression_hardening command
internal/public_api_contracts command
internal/validation_parity command
integration
models

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.