@stacksjs/database 0.70.88 → 0.70.90

package/dist/drivers/dynamodb.d.ts

@@ -0,0 +1,200 @@
+import type { Model } from '@stacksjs/types';
+/**
+ * Marshall a JS object to DynamoDB format
+ */
+declare function marshall(obj: Record<string, unknown>): DynamoItem;
+/**
+ * Unmarshall a DynamoDB object to JS format
+ */
+declare function unmarshall(obj: DynamoItem): Record<string, unknown>;
+/**
+ * Generate key pattern for an entity
+ */
+export declare function generateKeyPattern(entityName: string, idField?: string): string;
+/**
+ * Parse a key pattern and extract values
+ */
+export declare function parseKeyPattern(pattern: string, key: string): Record<string, string>;
+/**
+ * Build a key from a pattern and values
+ */
+export declare function buildKey(pattern: string, values: Record<string, string>): string;
+/**
+ * Create a new DynamoDB client instance
+ */
+export declare function createDynamo(): DynamoClient;
+/**
+ * DynamoDB client singleton
+ */
+export declare const dynamo: DynamoClient;
+/**
+ * Minimal AWS-SDK `DynamoDBClient` shape — just the methods this
+ * driver calls. Typed locally so callers wiring their own SDK
+ * client into `setClient()` get a clear compile-time contract
+ * instead of a runtime "function not found" surprise.
+ */
+export declare interface DynamoSdkClient {
+  query: (req: Record<string, unknown>) => Promise<{
+    Items?: DynamoItem[]
+    Count?: number
+    ScannedCount?: number
+    LastEvaluatedKey?: DynamoItem
+  }>
+  scan: (req: Record<string, unknown>) => Promise<{
+    Items?: DynamoItem[]
+    Count?: number
+    ScannedCount?: number
+    LastEvaluatedKey?: DynamoItem
+  }>
+  getItem: (req: Record<string, unknown>) => Promise<{ Item?: DynamoItem }>
+  putItem: (req: Record<string, unknown>) => Promise<unknown>
+  deleteItem: (req: Record<string, unknown>) => Promise<unknown>
+  updateItem: (req: Record<string, unknown>) => Promise<unknown>
+  batchWriteItem: (req: Record<string, unknown>) => Promise<unknown>
+  transactWriteItems: (req: Record<string, unknown>) => Promise<unknown>
+}
+/**
+ * DynamoDB connection configuration
+ */
+export declare interface DynamoConnectionConfig {
+  region: string
+  table: string
+  endpoint?: string
+  credentials?: {
+    accessKeyId: string
+    secretAccessKey: string
+    sessionToken?: string
+  }
+  pkAttribute?: string
+  skAttribute?: string
+  entityTypeAttribute?: string
+  keyDelimiter?: string
+}
+/**
+ * Entity mapping for single-table design
+ */
+export declare interface SingleTableEntityMapping {
+  entityType: string
+  pkPattern: string
+  skPattern?: string
+  gsi1pk?: string
+  gsi1sk?: string
+  gsi2pk?: string
+  gsi2sk?: string
+}
+/**
+ * Sort key builder for fluent API
+ */
+export declare interface SortKeyBuilder {
+  equals(value: string): EntityQueryBuilder
+  beginsWith(prefix: string): EntityQueryBuilder
+  between(start: string, end: string): EntityQueryBuilder
+  lt(value: string): EntityQueryBuilder
+  lte(value: string): EntityQueryBuilder
+  gt(value: string): EntityQueryBuilder
+  gte(value: string): EntityQueryBuilder
+}
+/**
+ * Batch write operation
+ */
+export declare interface BatchWriteOperation {
+  put?: { entity: string, item: Record<string, unknown> }
+  delete?: { entity: string, pk: string, sk: string }
+}
+/**
+ * Transact write operation
+ */
+export declare interface TransactWriteOperation {
+  put?: { entity: string, item: Record<string, unknown>, condition?: string }
+  update?: { entity: string, pk: string, sk?: string, set?: Record<string, unknown>, add?: Record<string, number>, remove?: string[] }
+  delete?: { entity: string, pk: string, sk: string, condition?: string }
+  conditionCheck?: { entity: string, pk: string, sk: string, condition: string }
+}
+/**
+ * Query result
+ */
+export declare interface QueryResult<T = unknown> {
+  items: T[]
+  count: number
+  scannedCount?: number
+  lastKey?: Record<string, unknown>
+}
+/**
+ * DynamoDB AttributeValue discriminated union (stacksjs/stacks#1894 T-8).
+ *
+ * Mirrors the wire format AWS SDK's `DynamoDBClient` produces and
+ * consumes, declared locally so this package doesn't take a hard
+ * dependency on `@aws-sdk/client-dynamodb` just for its types. Each
+ * concrete variant carries its own typed payload; consumers narrow
+ * via `'S' in attr` / etc.
+ *
+ * Why not just import from AWS SDK: the framework's DynamoDB driver
+ * ships as an optional peer integration. Pulling AWS SDK as a type-
+ * level dep would force every Stacks app to install it whether or
+ * not they use the driver.
+ */
+export type DynamoAttributeValue = | { S: string }
+  | { N: string }
+  | { B: Uint8Array | string }
+  | { BOOL: boolean }
+  | { NULL: true }
+  | { L: DynamoAttributeValue[] }
+  | { M: Record<string, DynamoAttributeValue> }
+  | { SS: string[] }
+  | { NS: string[] }
+  | { BS: Array<Uint8Array | string> }
+/** Marshalled item — the on-the-wire representation. */
+export type DynamoItem = Record<string, DynamoAttributeValue>;
+/**
+ * Entity-centric query builder for DynamoDB
+ */
+export declare class EntityQueryBuilder<T = unknown> {
+  constructor(client: DynamoSdkClient | undefined, tableName: string, config: { pkAttribute: string, skAttribute: string, entityTypeAttribute: string, keyDelimiter: string });
+  entity(entityType: string): this;
+  pk(value: string): this;
+  get sk(): SortKeyBuilder;
+  index(indexName: string): this;
+  project(...attributes: string[]): this;
+  filter(attribute: string, operator: string, value?: unknown): this;
+  where(attribute: string, value: unknown): this;
+  whereIn(attribute: string, values: unknown[]): this;
+  limit(count: number): this;
+  asc(): this;
+  desc(): this;
+  consistent(): this;
+  startFrom(key: Record<string, unknown>): this;
+  toRequest(): Record<string, unknown>;
+  get(): Promise<T[]>;
+  first(): Promise<T | undefined>;
+  getAll(): Promise<T[]>;
+  count(): Promise<number>;
+}
+/**
+ * DynamoDB client with entity-centric API
+ */
+declare class DynamoClient {
+  connection(config: DynamoConnectionConfig): this;
+  isConfigured(): boolean;
+  setClient(client: DynamoSdkClient): this;
+  getClient(): DynamoSdkClient | undefined;
+  registerEntity(mapping: SingleTableEntityMapping): this;
+  registerModel(model: Model): this;
+  getEntityMapping(entityType: string): SingleTableEntityMapping | undefined;
+  entity<T = any>(entityType: string): EntityQueryBuilder<T>;
+  batchWrite(operations: BatchWriteOperation[]): Promise<void>;
+  transactWrite(operations: TransactWriteOperation[]): Promise<void>;
+  put(entity: string, item: Record<string, unknown>): Promise<void>;
+  get<T = any>(pk: string, sk?: string): Promise<T | undefined>;
+  delete(pk: string, sk?: string): Promise<void>;
+  update(pk: string, sk: string | undefined, updates: Record<string, unknown>): Promise<void>;
+  getTableName(): string;
+  getConfig(): {
+    tableName: string
+    pkAttribute: string
+    skAttribute: string
+    entityTypeAttribute: string
+    keyDelimiter: string
+  };
+}
+// Export marshall/unmarshall utilities
+export { marshall, unmarshall };