dynotable-orm API: transactions, client and errors

How do transactions work in dynotable-orm?

transaction([...]) sends one TransactWriteItems request. Its entries come from each model's transaction.create, update, delete and condition, mixed with raw TransactItems. It throws before sending for more than 100 entries or for two entries on one key. A canceled transaction re-throws the SDK error unchanged, with reasons: one code per entry.

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {isConditionalCheckFailed, model, setClient, setDefaults, transaction} from 'dynotable-orm';
import {z} from 'zod';

setClient(new DynamoDBClient({region: 'eu-west-1'}));
setDefaults({prefix: 'prod-'}); // every table name is now prod-<name>

const Stock = model('Stock', z.object({sku: z.string(), count: z.number()}), {hashKey: 'sku'});

try {
  await Stock.create({sku: 'a', count: 1});
} catch (e) {
  if (!isConditionalCheckFailed(e)) throw e; // 'a' is already stored
}

try {
  await transaction([
    Stock.transaction.update({sku: 'a'}, {$ADD: {count: -1}}),
    Stock.transaction.create({sku: 'b', count: 1})
  ]);
} catch (e) {
  console.log((e as {reasons?: string[]}).reasons); // e.g. ['None', 'ConditionalCheckFailed']
}

ConfigError, ExpressionError, ValidationError and MarshallError are thrown before a request is sent: a model definition that cannot work, a request DynamoDB would reject, an item the schema rejects, and a value DynamoDB cannot store. toJSON and converter keep two dynamoose helpers.

transaction()

Call Signature

function transaction(items, options): Promise<TransactWriteItemsCommandInput>;

Sends TransactWriteItems with the entries of the models' transaction.*, mixed with raw TransactItems. It throws before sending for more than 100 entries or two entries on one key. The client is the client option, else getClient(). A canceled transaction re-throws the SDK error unchanged, with reasons: the CancellationReasons code of each entry, in order ('None' for the entries that passed), and items: the stored item each entry's failed condition returned (ReturnValuesOnConditionCheckFailure), read by its model, else undefined.

Parameters

Returns

Promise<TransactWriteItemsCommandInput>

Call Signature

function transaction(items, options?): Promise<void>;

Sends TransactWriteItems with the entries of the models' transaction.*, mixed with raw TransactItems. It throws before sending for more than 100 entries or two entries on one key. The client is the client option, else getClient(). A canceled transaction re-throws the SDK error unchanged, with reasons: the CancellationReasons code of each entry, in order ('None' for the entries that passed), and items: the stored item each entry's failed condition returned (ReturnValuesOnConditionCheckFailure), read by its model, else undefined.

Parameters

Returns

Promise<void>

orm

const orm: object;

The lib's top-level calls as one object, for test spies: vi.spyOn(orm, 'transaction') sees every transaction() call. A named ESM import cannot be spied on, as vi.spyOn(dynamoose, 'transaction') could.

Type Declaration

TransactionOptions type

Extends

• CallOptions

Properties

BatchGetOptions type

Extends

• CallOptions

Type Parameters

Properties

BatchGetResponse type

type BatchGetResponse<T> = T[] & object;

The items found, in the order of the keys. unprocessedKeys holds the stored keys DynamoDB left unread after the retries.

Type Parameters

Type Declaration

setClient()

function setClient(c?): void;

The client every model uses, unless the model option or a call's client gives another. Without an argument, the next call gets a new client with the SDK's default configuration, as dynamoose's aws.ddb.revert().

Parameters

Returns

void

getClient()

function getClient(): DynamoDBClient;

Created on first use with the SDK's default configuration, when setClient was not called.

Returns

DynamoDBClient

setDefaults()

function setDefaults(d): void;

The table-name prefix and suffix of every model that does not set its own. Replaces the earlier defaults, as dynamoose's Table.defaults.set.

Parameters

Returns

void

isConditionalCheckFailed()

function isConditionalCheckFailed(e): boolean;

True for the SDK error of a write whose condition failed. Matched by name, so any SDK copy's error class counts.

Parameters

Returns

boolean

ConfigError

A model definition that cannot work. Thrown by model(), extend(), createTableInput() and extendZod(), before any request is sent. Also thrown by the first call that parses a key, condition or query value whose field has an async check or transform: those values are parsed synchronously, and only a call shows that a check is async.

Extends

• Error

Constructors

Constructor

new ConfigError(message?): ConfigError;

Parameters

Returns

ConfigError

Inherited from

Error.constructor

Constructor

new ConfigError(message?, options?): ConfigError;

Parameters

Returns

ConfigError

Inherited from

Error.constructor

Properties

ExpressionError

A path, an update, a condition, a key, a batch or a transaction that DynamoDB would reject. Thrown before any request is sent.

Extends

• Error

Constructors

Constructor

new ExpressionError(message?): ExpressionError;

Parameters

Returns

ExpressionError

Inherited from

Error.constructor

Constructor

new ExpressionError(message?, options?): ExpressionError;

Parameters

Returns

ExpressionError

Inherited from

Error.constructor

Properties

ValidationError

The schema rejected an item. path is the path of the first issue. A value outside an enum and a value of the wrong type are told in dynamoose's words, which callers and tests match: status must equal ["A","B"], but is set to C, Expected note to be of type string, instead found type null.. Any other issue keeps the schema's message.

Extends

• Error

Constructors

Constructor

new ValidationError(issues, valueAt?): ValidationError;

valueAt reads the rejected value at an issue's path, for the dynamoose wording.

Parameters

Returns

ValidationError

Overrides

Error.constructor

Properties

MarshallError

Extends

• Error

Constructors

Constructor

new MarshallError(reason): MarshallError;

Parameters

Returns

MarshallError

Overrides

Error.constructor

Properties

toJSON()

Call Signature

function toJSON(x): Record<string, any>[];

dynamoose's item.toJSON(): a JSON round trip, so a Date becomes its ISO string and a Set an empty object.

Parameters

Returns

Record<string, any>[]

Call Signature

function toJSON(x): Record<string, any>;

dynamoose's item.toJSON(): a JSON round trip, so a Date becomes its ISO string and a Set an empty object.

Parameters

Returns

Record<string, any>

converter

const converter: object;

The @aws-sdk/util-dynamodb functions that dynamoose's aws.converter() returns, with their options.

Type Declaration