fluxor-cloud-db 1.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,34 @@
+name: Node.js Package
+
+# Trigger on push to main
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      # No test enforcement at this point, there's no local database servers etc...
+      # in github's runner. All unit tests must be done offline, this means manual
+      # verification is required per PR.
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.npm_token }}

package/README.md

@@ -0,0 +1,296 @@
+# fluxor-cloud-db
+
+Database adapter layer for [fluxor-cloud](https://github.com/hudson1998x/fluxor) services. Provides a unified query interface over DynamoDB and MongoDB, with a shared `WhereClause` / operator syntax so switching backends requires minimal code changes.
+
+---
+
+## Installation
+
+```bash
+npm install fluxor-cloud-db
+```
+
+---
+
+## Adapters
+
+| Adapter | Backend |
+|---|---|
+| `DynamoService` | AWS DynamoDB |
+| `MongoService` | MongoDB |
+
+---
+
+## Setup
+
+Both adapters follow the same lifecycle: configure, connect.
+
+### DynamoDB
+
+```typescript
+import { useDynamo } from 'fluxor-cloud-db';
+
+const dynamo = useDynamo();
+
+dynamo.setConfig({
+    region: process.env.AWS_REGION,
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    endpoint: process.env.DYNAMO_ENDPOINT
+});
+
+await dynamo.connect();
+```
+
+| Field | Required | Description |
+|---|:---:|---|
+| `region` | ✓ | AWS region, e.g. `us-east-1` |
+| `accessKeyId` | ✓ | AWS access key ID |
+| `secretAccessKey` | ✓ | AWS secret access key |
+| `endpoint` | ✓ | Custom endpoint, e.g. `http://localhost:8000` for local DynamoDB |
+
+### MongoDB
+
+```typescript
+import { useMongo } from 'fluxor-cloud-db';
+
+const mongo = useMongo();
+
+mongo.setConfig({
+    uri: process.env.MONGO_URI,
+    dbName: process.env.MONGO_DB_NAME,
+    authSource: process.env.MONGO_AUTH_SOURCE,
+    retryWrites: true,
+    w: 'majority'
+});
+
+await mongo.connect();
+```
+
+| Field | Required | Description |
+|---|:---:|---|
+| `uri` | ✓ | MongoDB connection string, e.g. `mongodb://localhost:27017` |
+| `dbName` | ✓ | Database name to connect to |
+| `authSource` | ✓ | Authentication database, e.g. `admin` |
+| `retryWrites` | ✓ | Whether to retry failed writes. Default `true` |
+| `w` | — | Write concern. Default `'majority'` |
+
+---
+
+## Query Operators
+
+Both adapters share the same `WhereClause` operator syntax.
+
+| Operator | Description | DynamoDB | MongoDB |
+|---|---|:---:|:---:|
+| `=` | Equals | ✓ | ✓ |
+| `!=` | Not equals | ✓ | ✓ |
+| `>` | Greater than | ✓ | ✓ |
+| `>=` | Greater than or equal | ✓ | ✓ |
+| `<` | Less than | ✓ | ✓ |
+| `<=` | Less than or equal | ✓ | ✓ |
+| `IN` | Value in list | ✓ | ✓ |
+| `NOT_IN` | Value not in list | ✓ | ✓ |
+| `BEGINS_WITH` | String prefix match | ✓ | ✓ |
+| `LIKE` | Case-insensitive substring | — | ✓ |
+| `BETWEEN` | Inclusive range | — | ✓ |
+| `EXISTS` | Field presence check | — | ✓ |
+
+Conditions can be written as raw objects or using the query builder helpers.
+
+### Raw syntax
+
+```typescript
+{ id: { operator: '=', value: 42 } }
+
+{
+    status: { operator: '=', value: 'active' },
+    score:  { operator: '>=', value: 100 }
+}
+```
+
+### Query builder
+
+```typescript
+import { eq, neq, gt, gte, lt, lte, anyOf, noneOf, startsWith, between, like, exists } from 'fluxor-cloud-db';
+
+{ id: eq(1) }
+{ id: neq(1) }
+{ score: gt(100) }
+{ score: gte(100) }
+{ score: lt(100) }
+{ score: lte(100) }
+{ id: anyOf([1, 2, 3]) }
+{ id: noneOf([4, 5, 6]) }
+{ username: startsWith('ali') }
+{ price: between(10, 50) }     // MongoDB only
+{ bio: like('engineer') }      // MongoDB only
+{ deletedAt: exists(false) }   // MongoDB only
+```
+
+Aliases are available for a more descriptive style:
+
+```typescript
+import { equals, notEquals, inList, notInList } from 'fluxor-cloud-db';
+
+{ id: equals(1) }
+{ id: notEquals(1) }
+{ id: inList([1, 2, 3]) }
+{ id: notInList([4, 5, 6]) }
+```
+
+---
+
+## API
+
+All methods are identical across both adapters.
+
+### `selectOne(tableName, where, options?)`
+
+Returns a single matching record, or `null` if not found.
+
+```typescript
+const user = await dynamo.selectOne('users', { id: eq(1) });
+
+// With projection
+const user = await dynamo.selectOne('users',
+    { id: eq(1) },
+    { projection: ['id', 'name', 'email'] }
+);
+```
+
+### `selectMany(tableName, where?, options?)`
+
+Returns a paginated result set.
+
+```typescript
+const { items, total, hasMore } = await mongo.selectMany('users',
+    { status: eq('active') },
+    {
+        limit: 20,
+        offset: 0,
+        orderBy: [{ field: 'createdAt', direction: 'DESC' }],
+        projection: ['id', 'name']
+    }
+);
+```
+
+### `createOne(tableName, data)`
+
+Inserts a single record and returns it.
+
+```typescript
+const user = await dynamo.createOne('users', {
+    id: 1,
+    name: 'Alice',
+    status: 'active'
+});
+```
+
+### `createMany(tableName, data, options?)`
+
+Inserts multiple records. DynamoDB batches in groups of 25 (AWS limit); MongoDB uses a single `insertMany`.
+
+```typescript
+const { items, result } = await mongo.createMany('users', [
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+]);
+
+// result: { successful: 2, failed: 0 }
+```
+
+| Option | Description |
+|---|---|
+| `stopOnError` | Stop processing on the first failed batch. Default `false` |
+
+### `updateOne(tableName, update, where)`
+
+Updates a single matching record and returns the updated document. Throws `DatabaseAdapterError` with code `NOT_FOUND` if no record matches.
+
+```typescript
+const updated = await dynamo.updateOne(
+    'users',
+    { status: 'inactive' },
+    { id: eq(1) }
+);
+```
+
+### `updateMany(tableName, update, where?, options?)`
+
+Updates all records matching the where clause. Returns the updated items and a batch result.
+
+```typescript
+const { items, result } = await mongo.updateMany(
+    'users',
+    { status: 'inactive' },
+    { score: lt(10) },
+    { limit: 100 }
+);
+
+// result: { successful: number, failed: number }
+```
+
+### `deleteOne(tableName, where)`
+
+Deletes a single matching record. Returns `{ success: false, deletedCount: 0 }` if no record matches — does not throw.
+
+```typescript
+const { success, deletedCount } = await dynamo.deleteOne('users', { id: eq(1) });
+```
+
+### `deleteMany(tableName, where?, options?)`
+
+Deletes all records matching the where clause. Returns a count of deleted records and a batch result.
+
+```typescript
+const { success, deletedCount, result } = await mongo.deleteMany(
+    'users',
+    { status: eq('inactive') },
+    { limit: 50 }
+);
+```
+
+---
+
+## Error Handling
+
+All methods throw `DatabaseAdapterError` on failure. The error includes a `code` for programmatic handling.
+
+```typescript
+import { DatabaseAdapterError } from 'fluxor-cloud-db';
+
+try {
+    await dynamo.updateOne('users', { name: 'Bob' }, { id: eq(999) });
+} catch (err) {
+    if (err instanceof DatabaseAdapterError) {
+        console.error(err.code);    // 'NOT_FOUND'
+        console.error(err.message); // 'Record not found'
+    }
+}
+```
+
+| Code | When |
+|---|---|
+| `NOT_CONNECTED` | Operation called before `connect()` |
+| `INVALID_CONFIG` | Missing or invalid configuration |
+| `MISSING_REGION` | DynamoDB `region` not provided |
+| `INVALID_CREDENTIALS` | Only one of `accessKeyId` / `secretAccessKey` provided |
+| `NOT_FOUND` | `updateOne` target does not exist |
+| `INVALID_INPUT` | e.g. `createMany` called with a non-array |
+| `OPERATION_FAILED` | Underlying driver error |
+| `NOT_IMPLEMENTED` | `executeRaw` is not supported |
+
+---
+
+## Lifecycle
+
+```typescript
+await service.connect();
+
+const alive = await service.healthCheck(); // true / false
+
+const connected = service.isConnected(); // synchronous
+
+await service.disconnect();
+```

package/dist/index.d.mts

@@ -0,0 +1,347 @@
+type DynamoConfig = {
+    region: string;
+    endpoint: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+};
+
+type QueryOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "IN" | "NOT_IN" | "BETWEEN" | "LIKE" | "EXISTS" | "BEGINS_WITH";
+/**
+ * Represents a single condition in a WHERE clause
+ */
+interface QueryCondition {
+    operator: QueryOperator;
+    value: any;
+}
+/**
+ * Represents a single field condition or nested conditions
+ */
+interface WhereClause {
+    [key: string]: QueryCondition | QueryCondition[] | WhereClause;
+}
+/**
+ * Represents update operations on specific fields
+ */
+interface UpdateClause {
+    [key: string]: any;
+}
+/**
+ * Configuration for query operations
+ */
+interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    orderBy?: {
+        field: string;
+        direction: "ASC" | "DESC";
+    }[];
+    projection?: string[];
+    consistent?: boolean;
+}
+/**
+ * Result wrapper for paginated responses
+ */
+type PaginatedResult<T> = {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+    nextOffset?: number;
+};
+/**
+ * Result wrapper for batch operations
+ */
+interface BatchResult {
+    successful: number;
+    failed: number;
+    errors?: {
+        index: number;
+        error: string;
+    }[];
+}
+
+/**
+ * Unified database adapter interface
+ * Supports DynamoDB, MongoDB, SQL databases, and other data stores
+ */
+interface DatabaseAdapter {
+    /**
+     * Establish connection to the database
+     * Implementation varies by backend (DynamoDB, MongoDB, etc.)
+     */
+    connect(): Promise<void>;
+    /**
+     * Close connection to the database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if adapter is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Fetch a single record matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions
+     * @param options - Query options (projection, consistency, etc.)
+     * @returns Single record or null if not found
+     */
+    selectOne<T = Record<string, any>>(tableName: string, where: WhereClause, options?: QueryOptions): Promise<T | null>;
+    /**
+     * Fetch multiple records matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions
+     * @param options - Query options (limit, offset, orderBy, projection, etc.)
+     * @returns Array of matching records with pagination info
+     */
+    selectMany<T = Record<string, any>>(tableName: string, where?: WhereClause, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    /**
+     * Insert a single record
+     * @param tableName - Table/collection name
+     * @param data - Record to insert
+     * @returns Created record with any server-generated fields
+     */
+    createOne<T = Record<string, any>>(tableName: string, data: Record<string, any>): Promise<T>;
+    /**
+     * Insert multiple records in a batch operation
+     * @param tableName - Table/collection name
+     * @param data - Array of records to insert
+     * @param options - Batch options (e.g., stopOnError)
+     * @returns Batch operation result with success/failure counts
+     */
+    createMany<T = Record<string, any>>(tableName: string, data: Record<string, any>[], options?: {
+        stopOnError?: boolean;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    /**
+     * Update a single record matching the where conditions
+     * @param tableName - Table/collection name
+     * @param update - Fields to update
+     * @param where - Query conditions to identify record
+     * @returns Updated record
+     */
+    updateOne<T = Record<string, any>>(tableName: string, update: UpdateClause, where: WhereClause): Promise<T>;
+    /**
+     * Update multiple records matching the where conditions
+     * @param tableName - Table/collection name
+     * @param update - Fields to update
+     * @param where - Query conditions to identify records
+     * @param options - Update options (e.g., limit)
+     * @returns Batch operation result with updated count
+     */
+    updateMany<T = Record<string, any>>(tableName: string, update: UpdateClause, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    /**
+     * Delete a single record matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions to identify record
+     * @returns Deleted record or confirmation
+     */
+    deleteOne(tableName: string, where: WhereClause): Promise<{
+        success: boolean;
+        deletedCount: number;
+    }>;
+    /**
+     * Delete multiple records matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions to identify records
+     * @param options - Delete options (e.g., limit)
+     * @returns Batch operation result with deleted count
+     */
+    deleteMany(tableName: string, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        result: BatchResult;
+    }>;
+    /**
+     * Execute a raw query specific to the database backend
+     * Use sparingly for complex queries not supported by the adapter
+     */
+    executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * Start a transaction (if supported by the backend)
+     */
+    beginTransaction?(): Promise<void>;
+    /**
+     * Commit an active transaction
+     */
+    commitTransaction?(): Promise<void>;
+    /**
+     * Rollback an active transaction
+     */
+    rollbackTransaction?(): Promise<void>;
+    /**
+     * Check the health/status of the database connection
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+declare class DynamoService implements DatabaseAdapter {
+    private client;
+    private dynamoDBClient;
+    private isConnectedFlag;
+    private config;
+    setConfig(config: DynamoConfig): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    healthCheck(): Promise<boolean>;
+    selectOne<T = Record<string, any>>(tableName: string, where: WhereClause, options?: QueryOptions): Promise<T | null>;
+    selectMany<T = Record<string, any>>(tableName: string, where?: WhereClause, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    createOne<T = Record<string, any>>(tableName: string, data: Record<string, any>): Promise<T>;
+    createMany<T = Record<string, any>>(tableName: string, data: Record<string, any>[], options?: {
+        stopOnError?: boolean;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    updateOne<T = Record<string, any>>(tableName: string, update: UpdateClause, where: WhereClause): Promise<T>;
+    updateMany<T = Record<string, any>>(tableName: string, update: UpdateClause, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    deleteOne(tableName: string, where: WhereClause): Promise<{
+        success: boolean;
+        deletedCount: number;
+    }>;
+    deleteMany(tableName: string, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        result: BatchResult;
+    }>;
+    executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T>;
+    private validateConfig;
+    private getClient;
+    private buildKey;
+    private extractKey;
+    private isKeyQuery;
+    private buildProjection;
+    private buildKeyConditionExpression;
+    private buildFilterExpression;
+    private buildUpdateExpression;
+    private handleError;
+}
+
+/**
+ * MongoDB implementation of DatabaseAdapter interface
+ * This is a template implementation showing how to adapt another database backend
+ */
+
+interface MongoConfig {
+    uri: string;
+    dbName: string;
+    authSource?: string;
+    retryWrites?: boolean;
+    w?: "majority" | number;
+}
+declare class MongoService implements DatabaseAdapter {
+    private client;
+    private db;
+    private isConnectedFlag;
+    private config;
+    setConfig(config: MongoConfig): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    healthCheck(): Promise<boolean>;
+    selectOne<T = Record<string, any>>(tableName: string, where: WhereClause, options?: QueryOptions): Promise<T | null>;
+    selectMany<T = Record<string, any>>(tableName: string, where?: WhereClause, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    createOne<T = Record<string, any>>(tableName: string, data: Record<string, any>): Promise<T>;
+    createMany<T = Record<string, any>>(tableName: string, data: Record<string, any>[], options?: {
+        stopOnError?: boolean;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    updateOne<T = Record<string, any>>(tableName: string, update: UpdateClause, where: WhereClause): Promise<T>;
+    updateMany<T = Record<string, any>>(tableName: string, update: UpdateClause, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    deleteOne(tableName: string, where: WhereClause): Promise<{
+        success: boolean;
+        deletedCount: number;
+    }>;
+    deleteMany(tableName: string, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        result: BatchResult;
+    }>;
+    executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T>;
+    private validateConfig;
+    private getDb;
+    private getCollection;
+    private buildMongoFilter;
+    private isValidOperator;
+    private buildMongoUpdate;
+    private handleError;
+}
+
+interface Condition {
+    operator: string;
+    value: unknown;
+}
+declare const eq: (value: unknown) => Condition;
+declare const neq: (value: unknown) => Condition;
+declare const gt: (value: number | string) => Condition;
+declare const gte: (value: number | string) => Condition;
+declare const lt: (value: number | string) => Condition;
+declare const lte: (value: number | string) => Condition;
+/** Inclusive range. MongoDB only. */
+declare const between: (min: number | string, max: number | string) => Condition;
+declare const anyOf: (values: unknown[]) => Condition;
+declare const noneOf: (values: unknown[]) => Condition;
+declare const startsWith: (value: string) => Condition;
+/** Case-insensitive substring match. MongoDB only. */
+declare const like: (value: string) => Condition;
+/** Field presence check. MongoDB only. */
+declare const exists: (value?: boolean) => Condition;
+/** Alias for eq */
+declare const equals: (value: unknown) => Condition;
+/** Alias for neq */
+declare const notEquals: (value: unknown) => Condition;
+/** Alias for anyOf */
+declare const inList: (values: unknown[]) => Condition;
+/** Alias for noneOf */
+declare const notInList: (values: unknown[]) => Condition;
+
+/**
+ * Resolves the {@link DynamoService} instance from the service container.
+ *
+ * @example
+ * ```typescript
+ * const dynamo = useDynamo();
+ * const user = await dynamo.selectOne("users", { id: { operator: "=", value: 1 } });
+ * ```
+ *
+ * @returns The registered {@link DynamoService} instance.
+ */
+declare const useDynamo: () => DynamoService;
+/**
+ * Resolves the {@link MongoService} instance from the service container.
+ *
+ * @example
+ * ```typescript
+ * const mongo = useMongo();
+ * const users = await mongo.selectMany("users", { status: { operator: "=", value: "active" } });
+ * ```
+ *
+ * @returns The registered {@link MongoService} instance.
+ */
+declare const useMongo: () => MongoService;
+
+export { type DynamoConfig, DynamoService, type MongoConfig, MongoService, anyOf, between, eq, equals, exists, gt, gte, inList, like, lt, lte, neq, noneOf, notEquals, notInList, startsWith, useDynamo, useMongo };