@alt-javascript/jsnosqlc-dynamodb

JSNOSLQC driver for AWS DynamoDB via the @aws-sdk/client-dynamodb v3 SDK.

Part of the @alt-javascript/jsnosqlc monorepo.

Install

npm install @alt-javascript/jsnosqlc-core @alt-javascript/jsnosqlc-dynamodb

Usage

import { DriverManager, Filter } from '@alt-javascript/jsnosqlc-core';
import '@alt-javascript/jsnosqlc-dynamodb'; // self-registers with DriverManager

// Local DynamoDB (DynamoDB Local)
const client = await DriverManager.getClient('jsnosqlc:dynamodb:us-east-1', {
  endpoint: 'http://localhost:8000',
  credentials: { accessKeyId: 'local', secretAccessKey: 'local' },
});

// AWS production — uses standard AWS credential chain
const client = await DriverManager.getClient('jsnosqlc:dynamodb:us-east-1');

const orders = client.getCollection('orders');

await orders.store('ord-001', { customerId: 'c1', amount: 59.99, status: 'pending' });
const order = await orders.get('ord-001');

const id = await orders.insert({ customerId: 'c2', amount: 120.00, status: 'shipped' });
await orders.update(id, { status: 'delivered' });

const filter = Filter.where('status').eq('pending').build();
const cursor = await orders.find(filter);
const pending = cursor.getDocuments();

await client.close();

URL Scheme

jsnosqlc:dynamodb:<region>

| URL | Description | |---|---| | jsnosqlc:dynamodb:us-east-1 | AWS DynamoDB in us-east-1 | | jsnosqlc:dynamodb:eu-west-1 | AWS DynamoDB in eu-west-1 |

Connection Properties

| Property | Description | |---|---| | endpoint | Override endpoint URL (for DynamoDB Local or LocalStack) | | credentials | { accessKeyId, secretAccessKey } (falls back to standard AWS credential chain) |

const client = await DriverManager.getClient('jsnosqlc:dynamodb:us-east-1', {
  endpoint: process.env.DYNAMODB_ENDPOINT, // e.g. 'http://localhost:8000'
});

Table Management

Tables are created automatically when a collection is first used. Each collection maps to a DynamoDB table with a single String hash key named pk.

To use an existing table, ensure it has pk (String) as its partition key.

Local Development with Docker

docker run --rm -d -p 8000:8000 amazon/dynamodb-local:latest
export DYNAMODB_ENDPOINT=http://localhost:8000

const client = await DriverManager.getClient('jsnosqlc:dynamodb:us-east-1', {
  endpoint: process.env.DYNAMODB_ENDPOINT,
  credentials: { accessKeyId: 'local', secretAccessKey: 'local' },
});

Filter Translation

DynamoDB uses FilterExpressions for Scan operations. The driver translates the JSNOSLQC AST:

| JSNOSLQC | DynamoDB FilterExpression | |---|---| | eq | #field = :val | | ne | #field <> :val | | gt / gte | #field > / >= :val | | lt / lte | #field < / <= :val | | contains | contains(#field, :val) | | in | (#field = :v0 OR #field = :v1 ...) | | nin | (#field <> :v0 AND #field <> :v1 ...) | | exists (true) | attribute_exists(#field) | | exists (false) | attribute_not_exists(#field) | | and | (expr AND expr) | | or | (expr OR expr) | | not | NOT (expr) |

All find() calls use DynamoDB Scan with a FilterExpression. For large tables, add a secondary index and query by index key for production use cases.

License

MIT