@baselinejs/dynamodb/dist/index.d.mts

DynamoDB library for simple and optimized way to use AWS DynamoDB

import { DynamoDBClientConfig, AttributeValue } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
import { NativeAttributeValue, unmarshallOptions, marshallOptions } from '@aws-sdk/util-dynamodb';

type OperatorQueryType = 'BeginsWith' | 'LessThan' | 'GreaterThan' | 'LessThanEqual' | 'GreaterThanEqual' | 'Equal' | 'NotEqual' | 'Between';
/**
 * These additional operators are valid for condition expressions but not query expressions.
 */
type OperatorType = OperatorQueryType | 'AttributeExists' | 'AttributeNotExists';
interface ConditionExpressionArgs {
    operator: OperatorType;
    field: string;
    value?: NativeAttributeValue;
    /** Used only for Between comparison */
    betweenSecondValue?: NativeAttributeValue;
}
interface ConditionExpressionQueryArgs {
    operator: OperatorQueryType;
    field: string;
    value?: NativeAttributeValue;
    /** Used only for Between comparison */
    betweenSecondValue?: NativeAttributeValue;
}

type DynamoClientConfig = DynamoDBClientConfig & {
    region: string;
};
/**
 * Provided to get around conflicting versions of DynamoDBDocument from @aws-sdk/lib-dynamodb
 */
type DynamoDbDocumentClient = DynamoDBDocument;
/**
 * Creates a DynamoDBDocument connection.
 *
 * Must specify a region.
 *
 * Uses a local connection if IS_OFFLINE is set to "true" and FORCE_ONLINE is not set to "true".
 */
declare function getDynamodbConnection(config: DynamoClientConfig): DynamoDbDocumentClient;
interface PutItemParams<T extends Record<string, NativeAttributeValue>> {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    item: T;
    /**
     * Array of conditions to apply to the create.
     * Conditions are combined with AND.
     */
    conditions?: ConditionExpressionArgs[];
}
/**
 * Create a new item.
 */
declare const putItem: <T extends Record<string, any>>(params: PutItemParams<T>) => Promise<T>;
interface UpdateItemParams<T extends Record<string, NativeAttributeValue>> {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    key: Record<string, NativeAttributeValue>;
    /**
     * Record of fields to update.
     * Attributes from the "key" will be automatically removed from fields to prevent "This attribute is part of the key" errors.
     */
    fields?: Partial<Record<keyof T, NativeAttributeValue>>;
    /**
     * Array of attributes to remove from the item.
     */
    removeFields?: Extract<keyof T, string>[];
    /**
     * Array of conditions to apply to the update.
     * Conditions are combined with AND.
     */
    conditions?: ConditionExpressionArgs[];
}
/**
 * Update attributes on an item.
 *
 * Specify "fields" for the attributes to update.
 *
 * Specify "removeFields" for the attributes to remove from the item.
 *
 * Either "fields", "removeFields" or both must be specified.
 */
declare const updateItem: <T extends Record<string, any>>(params: UpdateItemParams<T>) => Promise<T>;
interface DeleteItemParams {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    key: Record<string, NativeAttributeValue>;
    /**
     * Array of conditions to apply to the delete.
     * Conditions are combined with AND.
     */
    conditions?: ConditionExpressionArgs[];
}
declare const deleteItem: (params: DeleteItemParams) => Promise<boolean>;
interface GetItemParams<K> {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    key: Record<string, NativeAttributeValue>;
    consistentRead?: boolean;
    /**
     * Specific attributes to be returned on the item.
     *
     * When using this provide the K type including each of these attributes.
     */
    projectionExpression?: K[];
}
/**
 * Get a single item.
 */
declare function getItem<T extends Record<string, NativeAttributeValue>>(params: GetItemParams<keyof T>): Promise<T>;
/**
 * Get a single item.
 *
 * Specify K when using a projectionExpression
 */
declare function getItem<T extends Record<string, NativeAttributeValue>, K extends keyof T>(params: GetItemParams<K>): Promise<Pick<T, K>>;
interface GetAllItemsParams<K> {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    /**
     * Limit the number of items returned.
     * This will continue fetching items until the limit is reached or there are no more items.
     */
    limit?: number;
    consistentRead?: boolean;
    /**
     * Array of conditions to apply to the scan.
     * Conditions are combined with AND.
     */
    filterConditions?: ConditionExpressionArgs[];
    /**
     * Specific attributes to be returned on each item.
     *
     * When using this provide the K type including each of these attributes.
     */
    projectionExpression?: K[];
    exclusiveStartKey?: Record<string, NativeAttributeValue>;
}
/**
 * Scan items from a table.
 */
declare function getAllItems<T extends Record<string, NativeAttributeValue>>(params: GetAllItemsParams<keyof T>): Promise<T[]>;
/**
 * Scan items from a table.
 */
declare function getAllItems<T extends Record<string, NativeAttributeValue>, K extends keyof T>(params: GetAllItemsParams<K>): Promise<Pick<T, K>[]>;
interface BatchGetItemsParams {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    /**
     * Keys of items to get.
     * Automatically handles chunking the keys by 100.
     */
    keys: Record<string, NativeAttributeValue>[];
}
/**
 * Batch get items from a table.
 * Automatically handles chunking the keys by 100.
 * Items are returned in an arbitrary order.
 */
declare const batchGetItems: <T extends Record<string, any>>(params: BatchGetItemsParams) => Promise<T[]>;
interface QueryItemsParams<K> {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    keyName: string;
    keyValue: NativeAttributeValue;
    /**
     * Which GSI or LSI to query.
     */
    indexName?: string;
    /**
     * Specify as false to query in reverse order.
     */
    scanIndexForward?: boolean;
    /**
     * Consistent reads for queries can only be done with no index specified or an LSI.
     */
    consistentRead?: boolean;
    /**
     * Limit the number of items returned.
     * This will continue fetching items until the limit is reached or there are no more items.
     */
    limit?: number;
    /**
     * Condition to be applied to the sort key.
     */
    rangeCondition?: ConditionExpressionQueryArgs;
    /**
     * Specific attributes to be returned on each item.
     *
     * When using this provide the K type including each of these attributes.
     */
    projectionExpression?: K[];
    exclusiveStartKey?: Record<string, NativeAttributeValue>;
}
/**
 * Query items from a table.
 */
declare function queryItems<T extends Record<string, NativeAttributeValue>>(params: QueryItemsParams<keyof T>): Promise<T[]>;
/**
 * Query items from a table.
 */
declare function queryItems<T extends Record<string, NativeAttributeValue>, K extends keyof T>(params: QueryItemsParams<K>): Promise<Pick<T, K>[]>;
interface QueryRangeParams<K> extends Omit<QueryItemsParams<K>, 'rangeCondition'> {
    rangeKeyName: string;
    rangeKeyValue: NativeAttributeValue;
    /**
     * Specify as true to use a begins_with condition on the sort key.
     * Specify as falsy to use an equals condition on the sort key.
     */
    fuzzy?: boolean;
}
/**
 * A wrapper for dynamoQuery that simplifies the usage of the sort key with an equals or begins_with condition.
 */
declare function queryItemsRange<T extends Record<string, NativeAttributeValue>>(params: QueryRangeParams<keyof T>): Promise<T[]>;
/**
 * A wrapper for dynamoQuery that simplifies the usage of the sort key with an equals or begins_with condition.
 */
declare function queryItemsRange<T extends Record<string, NativeAttributeValue>, K extends keyof T>(params: QueryRangeParams<K>): Promise<Pick<T, K>[]>;
interface QueryItemsRangeBetweenParams<K> extends Omit<QueryItemsParams<K>, 'rangeCondition'> {
    rangeKeyName: string;
    rangeKeyValueMin: NativeAttributeValue;
    rangeKeyValueMax: NativeAttributeValue;
}
/**
 * A wrapper for dynamoQuery that simplifies the usage of the sort key with a 'between' condition
 */
declare function queryItemsRangeBetween<T extends Record<string, NativeAttributeValue>>(params: QueryItemsRangeBetweenParams<keyof T>): Promise<T[]>;
/**
 * A wrapper for dynamoQuery that simplifies the usage of the sort key with a 'between' condition
 */
declare function queryItemsRangeBetween<T extends Record<string, NativeAttributeValue>, K extends keyof T>(params: QueryItemsRangeBetweenParams<K>): Promise<Pick<T, K>[]>;
interface BatchPutItems<T extends Record<string, NativeAttributeValue>> {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    /**
     * Items to create.
     * Automatically handles chunking the items by 25.
     */
    items: T[];
}
/**
 * Batch create items into a table.
 * Automatically handles chunking the items by 25.
 */
declare const batchPutItems: <T extends Record<string, any>>(params: BatchPutItems<T>) => Promise<T[]>;
interface BatchDeleteItemsParams {
    dynamoDb: DynamoDbDocumentClient;
    table: string;
    /**
     * Items to delete.
     * Automatically handles chunking the items by 25.
     */
    keys: Record<string, NativeAttributeValue>[];
}
/**
 * Batch delete items from a table.
 * Automatically handles chunking the keys by 25.
 */
declare const batchDeleteItems: (params: BatchDeleteItemsParams) => Promise<boolean>;
/**
 * Unmarshalling is used to convert a DynamoDB record into a JavaScript object.
 */
declare const unmarshallItem: <T extends Record<string, any>>(item: Record<string, AttributeValue>, options?: unmarshallOptions) => T;
/**
 * Marshalling is used to convert a JavaScript object into a DynamoDB record.
 */
declare const marshallItem: <T extends Record<string, any>>(item: T, options?: marshallOptions) => Record<string, AttributeValue>;

export { type BatchDeleteItemsParams, type BatchGetItemsParams, type BatchPutItems, type ConditionExpressionArgs, type ConditionExpressionQueryArgs, type DeleteItemParams, type DynamoClientConfig, type DynamoDbDocumentClient, type GetAllItemsParams, type GetItemParams, type PutItemParams, type QueryItemsParams, type QueryItemsRangeBetweenParams, type QueryRangeParams, type UpdateItemParams, batchDeleteItems, batchGetItems, batchPutItems, deleteItem, getAllItems, getDynamodbConnection, getItem, marshallItem, putItem, queryItems, queryItemsRange, queryItemsRangeBetween, unmarshallItem, updateItem };