dynotable-orm API: queries, scans and conditions

How do the query, scan and condition chains work?

Model.query(field) starts a query chain and Model.scan() a scan. Each call adds a condition or a setting, and nothing is sent until exec(). The result is an array of items with count and lastKey: pass lastKey to startAt() to read the next page. A Condition uses the same chain for the condition of a write.

import {model} from 'dynotable-orm';
import {z} from 'zod';

const Order = model(
  'Order',
  z.object({customerId: z.string(), orderId: z.string(), status: z.enum(['open', 'paid'])}),
  {hashKey: 'customerId', rangeKey: 'orderId'}
);

const page = await Order.query('customerId').eq('c1').where('status').eq('open').limit(25).exec();
const next = await Order.query('customerId').eq('c1').startAt(page.lastKey).exec();

await Order.update(
  {customerId: 'c1', orderId: 'o1'},
  {status: 'paid'},
  {condition: Order.condition().where('status').eq('open')}
);
console.log(page.count, next.length);

The query picks its index from the conditions unless using() names one. The update input types and ifNotExists are here too, because an update and a condition share their paths.

Query type

type Query<M> = Retriever<'query', TypesOf<M>, ItemOf<M>>;

Type Parameters

Scan type

type Scan<M> = Retriever<'scan', TypesOf<M>, ItemOf<M>>;

Type Parameters

QueryResponse type

Extends

• RetrieverResponse<T>

Type Parameters

Indexable

[n: number]: T

Properties

ScanResponse type

Extends

• RetrieverResponse<T>

Type Parameters

Indexable

[n: number]: T

Properties

ParallelScanResponse type

A parallel() scan's result: several unfinished segments give one key per segment.

Extends

• Omit<ScanResponse<T>, "lastKey">

Type Parameters

Indexable

[key: number]: T

Properties

Condition

A condition, built with the dynamoose chain. Calls change the instance and return it, as in dynamoose. Keys and values are checked and converted against a model when the condition is rendered.

Type Parameters

Constructors

Constructor

new Condition<T, K>(key?): Condition<T, K>;

Parameters

Returns

Condition<T, K>

Constructor

new Condition<T, K>(init): Condition<T, K>;

Parameters

Returns

Condition<T, K>

Methods

and()

and(): this;

Readability only: conditions are joined with AND by default.

Returns

this

attribute()

attribute<P>(key): Condition<T, P>;

Type Parameters

Parameters

Returns

Condition<T, P>

attributeExists()

attributeExists(): Condition<T>;

Returns

Condition<T>

attributeNotExists()

attributeNotExists(): Condition<T>;

Returns

Condition<T>

beginsWith()

beginsWith(value): Condition<T>;

Parameters

Returns

Condition<T>

between()

between(low, high): Condition<T>;

Parameters

Returns

Condition<T>

contains()

contains(value): Condition<T>;

A substring of a string, or an element of a Set or a list.

Parameters

Returns

Condition<T>

eq()

eq(value): Condition<T>;

Parameters

Returns

Condition<T>

exists()

exists(): Condition<T>;

Returns

Condition<T>

filter()

filter<P>(key): Condition<T, P>;

Type Parameters

Parameters

Returns

Condition<T, P>

ge()

ge(value): Condition<T>;

Parameters

Returns

Condition<T>

group()

group(condition): Condition<T>;

As in dynamoose, group calls parenthesis, so a spy on parenthesis sees both.

Parameters

Returns

Condition<T>

gt()

gt(value): Condition<T>;

Parameters

Returns

Condition<T>

in()

in(values): Condition<T>;

Parameters

Returns

Condition<T>

le()

le(value): Condition<T>;

Parameters

Returns

Condition<T>

lt()

lt(value): Condition<T>;

Parameters

Returns

Condition<T>

ne()

ne(value): Condition<T>;

Parameters

Returns

Condition<T>

not()

not(): this;

Negates the next comparison. beginsWith, in and between cannot be negated.

Returns

this

or()

or(): Condition<T>;

Returns

Condition<T>

parenthesis()

parenthesis(condition): Condition<T>;

Parameters

Returns

Condition<T>

toNode()

toNode(plan): ConditionNode | undefined;

Internal

The condition tree, or undefined when nothing was added. Throws on a key the model does not declare.

Parameters

Returns

ConditionNode | undefined

where()

where<P>(key): Condition<T, P>;

Type Parameters

Parameters

Returns

Condition<T, P>

ConditionInput type

type ConditionInput = Condition<any, any> | RawCondition;

A dynamoose condition, checked against the model when the request is built, or a raw condition object.

RawCondition type

A raw condition object, passed through as is.

Properties

UpdateInput type

type UpdateInput<T> = IsAny<T> extends true ? Record<string, any> : SetInput<T> & object;

Plain fields are an implicit $SET.

Type Parameters

UpdateInputOf type

type UpdateInputOf<M> = UpdateInput<TypesOf<M>['input']>;

What update takes: the schema's input, which it parses.

Type Parameters

UpdateOptions type

'ALL_OLD': when the condition fails, DynamoDB returns the stored item, and the thrown SDK error (its class unchanged) carries it read back as get reads it, in item.

Extends

• CallOptions
• ConditionFailureOptions

Properties

ifNotExists()

function ifNotExists<V>(value): IfNotExists<V>;

Type Parameters

Parameters

Returns

IfNotExists<V>

IfNotExists type

A $SET value written only when the attribute is not stored yet: SET p = if_not_exists(p, v).

Type Parameters

Properties