@patternmeshjs/core

The core modeling package for patternmesh.

It provides:

• table and entity declarations
• access-pattern compilation
• typed repositories
• update builders and conditions
• transactions, batch APIs, relations, read bundles, and write recipes
• lifecycle recipes (softDelete, archive)

Install

pnpm add @patternmeshjs/core

Requirements:

• Node 18+
• ESM-only

Public API reference

Table and keys

• defineTable
• key
• Brand

Field builders

• string
• number
• boolean
• datetime
• enumType
• id
• json
• ttl
• object
• record
• list
• stringSet
• numberSet
• fieldRef
• pathRef

Field and schema types

• FieldDef
• SchemaRecord
• InferItem
• CreateInput
• PrimaryKeyInput
• SettableShape
• AddableShape
• RemovableKeys
• FieldRef

Entity compilation

• entity
• CompiledEntity
• COMPILED_ENTITY

Connection and repositories

• connect
• ConnectOptions
• ConnectedDb

Each repository exposes:

• create(data, options?) — strict not-exists write
• put(data, options?) — unconditional write
• get(key)
• delete(key, options?)
• find.<pattern>(input)
• batchGet(keys)
• batchWrite({ puts, deletes })
• update(key)
• explain.create
• explain.put
• explain.get
• explain.delete
• explain.find.<pattern>
• explain.batchGet
• explain.batchWrite

Relations, bundles, and recipes

• createRelations
• createReadBundles
• createWriteRecipes
• RelationBuilder
• ReadBundleBuilder
• ReadBundleStepBuilder
• WriteRecipeBuilder
• WriteRecipeStepBuilder
• RelationDecl
• RelationsConfig
• HasManyDecl
• BelongsToDecl
• HasManyThroughDecl
• ReadBundleStepDecl
• ReadBundleDecl
• ReadBundlesConfig
• WriteRecipeStepDecl
• WriteRecipeDecl
• WriteRecipesConfig

Transactions

• TRANSACT_MAX_ITEMS
• TransactWriteBuilder
• TransactReadBuilder
• createTransactServices

Core types

• CompiledOperation
• Page
• OpaqueCursor
• DynamoReadPlan
• AccessPatternDef
• FieldMeta
• BatchChunkPlan
• QuerySelectMode
• ReturnConsumedCapacityMode

Adapter-facing types

• DynamoAdapter
• GetItemInput
• PutItemInput
• DeleteItemInput
• DeleteItemOutput
• QueryInput
• UpdateItemInput
• QueryOutput
• ScanInput
• ScanOutput
• ConsumedCapacity
• PutItemOutput
• BatchGetItemInput
• BatchGetItemOutput
• BatchWriteItemInput
• BatchWriteItemOutput
• BatchWritePut
• BatchWriteDelete
• TransactGetSlot
• TransactGetItemsInput
• TransactGetItemsOutput
• TransactWriteItemInput
• TransactWriteItemsInput

Errors

• DynamoModelError
• ValidationError
• ConfigurationError
• ConditionFailedError
• ItemAlreadyExistsError
• NotUniqueError
• QueryLimitError
• BatchWriteExhaustedError
• BatchGetExhaustedError
• TransactionCanceledError
• IdempotentParameterMismatchError
• TransactionCancellationReason

Utilities

• createAccessPatternFactory
• BATCH_GET_MAX_KEYS
• BATCH_WRITE_MAX_OPS
• chunkArray
• CreateReturnMode
• DeleteReturnMode
• encodeCursor
• decodeCursor

Behavioral contracts

Repository semantics

• create() enforces attribute_not_exists(partitionKey) and throws ItemAlreadyExistsError on collision.
• put() overwrites unconditionally.
• public items omit pk, sk, index key attributes, and the internal discriminator.

Batch contracts

• batchGet(keys) preserves input order and returns null for misses.
• batchWrite({ puts, deletes }) is chunked per DynamoDB limits and throws BatchWriteExhaustedError if unprocessed items remain after retries.

Query / scan rules

• ConsistentRead on a GSI route throws ValidationError.
• ap.count(...) is the supported COUNT surface.
• ap.scan(...) is explicit; there is no implicit repository scan.

Transactions

• db.tx.write supports at most 100 participants.
• duplicate write targets are rejected before calling DynamoDB.
• writes accept clientRequestToken for DynamoDB's 10-minute idempotency window.

Validation

• unknown create/update keys throw ValidationError
• empty Dynamo sets are rejected
• ttl() values must be non-negative integer epoch seconds
• json() values must be JSON-serializable
• cursor decoding validates shape and rejects malformed payloads

Modeling guidance

• Embed object, list, and set fields when data is bounded and read with the parent item.
• Prefer child items and explicit access patterns for large or independently queried collections.
• Reserve logical field names for domain data only; internal table/index attribute names are rejected.

Related docs

• Repository root README
• Single-table design guide
• Table setup guide

Topic cookbooks

• Relations cookbook
• Bundles and recipes
• Lifecycle recipes
• Complex attributes
• Streams advanced