qstd 0.2.27 → 0.3.0

package/dist/server/aws/ddb/types.d.ts

@@ -0,0 +1,216 @@
+import type { NativeAttributeValue } from "@aws-sdk/lib-dynamodb";
+import type { DynamoDBClient, DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";
+export type TableClient = DynamoDBClient;
+export type Credentials = DynamoDBClientConfig["credentials"];
+export type Key = {
+    pk: Pk;
+    sk: Sk;
+};
+export type StrWithAutocomplete<T> = T | (string & Record<never, never>);
+export type Pk = StrWithAutocomplete<"pk" | "gsi-pk" | "gsi2-pk" | "gsi-2-pk">;
+export type Sk = StrWithAutocomplete<"sk" | "gsi-sk" | "gsi2-sk" | "gsi-2-sk">;
+export type RawResponse<T> = {
+    lastEvaluatedKey?: Record<string, unknown> | undefined;
+    scannedCount: number;
+    count: number;
+    items: T[];
+};
+type RecursiveFn<T> = (page: RawResponse<T>, pageCount: number, totalItems: number) => boolean;
+export type SkCond = {
+    key?: Sk;
+    op: "=" | ">=" | ">" | "<=" | "<";
+    value: string;
+} | {
+    key?: Sk;
+    op: "begins_with";
+    value: string;
+} | {
+    key?: Sk;
+    op: "between";
+    value: [string, string];
+} | {
+    key?: Sk;
+    value: string;
+    valueBeginsWith?: never;
+} | {
+    key?: Sk;
+    valueBeginsWith: string;
+    value?: never;
+};
+type StrKey<T> = Extract<keyof T, string>;
+type Comparable = string | number | bigint;
+type AllowsOrder<V> = V extends Comparable ? true : false;
+type AllowsBeginsWith<V> = V extends string ? true : false;
+type AllowsContains<V> = V extends string ? true : V extends ReadonlyArray<unknown> | Array<unknown> | ReadonlySet<unknown> | Set<unknown> ? true : false;
+type AllowsBetween<V> = V extends Comparable ? true : false;
+type AllowsIn<V> = V extends Comparable ? true : false;
+type EqNeClause<T, K extends StrKey<T>> = {
+    key: K;
+    op: "=" | "<>";
+    value: T[K];
+};
+type OrdClause<T, K extends StrKey<T>> = AllowsOrder<T[K]> extends true ? {
+    key: K;
+    op: ">" | ">=" | "<" | "<=";
+    value: Extract<T[K], Comparable>;
+} : never;
+type BeginsWithClause<T, K extends StrKey<T>> = AllowsBeginsWith<T[K]> extends true ? {
+    key: K;
+    op: "begins_with";
+    value: Extract<T[K], string>;
+} : never;
+type ContainsClause<T, K extends StrKey<T>> = AllowsContains<T[K]> extends true ? T[K] extends string ? {
+    key: K;
+    op: "contains";
+    value: string;
+} : T[K] extends ReadonlyArray<infer U> | Array<infer U> | ReadonlySet<infer U> | Set<infer U> ? {
+    key: K;
+    op: "contains";
+    value: U;
+} : never : never;
+type BetweenClause<T, K extends StrKey<T>> = AllowsBetween<T[K]> extends true ? {
+    key: K;
+    op: "between";
+    value: readonly [Extract<T[K], Comparable>, Extract<T[K], Comparable>];
+} : never;
+type InClause<T, K extends StrKey<T>> = AllowsIn<T[K]> extends true ? {
+    key: K;
+    op: "in";
+    value: ReadonlyArray<Extract<T[K], Comparable>>;
+} : never;
+type ExistsClause<T, K extends StrKey<T>> = {
+    key: K;
+    op: "attribute_exists" | "attribute_not_exists";
+};
+type FilterClauseForKey<T, K extends StrKey<T>> = EqNeClause<T, K> | OrdClause<T, K> | BeginsWithClause<T, K> | ContainsClause<T, K> | BetweenClause<T, K> | InClause<T, K> | ExistsClause<T, K>;
+/** One clause type that's keyed & value-typed from T */
+export type FilterClause<T extends object> = {
+    [K in StrKey<T>]: FilterClauseForKey<T, K>;
+}[StrKey<T>];
+/** Shared props between Query and Scan operations */
+type BaseFindProps<T extends object = Record<string, unknown>> = {
+    /** Table name override (optional, defaults to main table) */
+    tableName?: string;
+    /**
+     * Type-safe filter clauses for post-query/scan filtering (optional)
+     * Array of filter clauses, all combined with AND logic
+     *
+     * Examples:
+     * ```ts
+     * // Equality check
+     * filters: [{ key: 'status', op: '=', value: 'active' }]
+     *
+     * // Multiple filters (AND logic)
+     * filters: [
+     *   { key: 'status', op: '=', value: 'active' },
+     *   { key: 'age', op: '>=', value: 18 },
+     *   { key: 'score', op: '>', value: 80 }
+     * ]
+     *
+     * // Existence checks
+     * filters: [
+     *   { key: 'email', op: 'attribute_exists' },
+     *   { key: 'deletedAt', op: 'attribute_not_exists' }
+     * ]
+     *
+     * // String operations
+     * filters: [
+     *   { key: 'name', op: 'begins_with', value: 'John' },
+     *   { key: 'description', op: 'contains', value: 'urgent' }
+     * ]
+     *
+     * // Range and list operations
+     * filters: [
+     *   { key: 'age', op: 'between', value: [18, 65] },
+     *   { key: 'status', op: 'in', value: ['active', 'pending', 'approved'] }
+     * ]
+     * ```
+     */
+    filters?: ReadonlyArray<FilterClause<T>>;
+    /** Limit number of items returned per page (optional) */
+    limit?: number;
+    /** Pagination token from previous query/scan (optional) */
+    startKey?: Record<string, NativeAttributeValue>;
+    /** Fetch all pages recursively; pass function to control continuation (optional) */
+    recursive?: boolean | RecursiveFn<T>;
+    /** Maximum items to fetch when using recursive (optional) */
+    maxItems?: number;
+    /** Maximum pages to fetch when using recursive (optional) */
+    maxPages?: number;
+    /** Use consistent reads (slower but guaranteed up-to-date, only works on tables not indexes) */
+    strong?: boolean;
+    /** Projection: specific attributes to retrieve (reduces data transfer) */
+    projection?: (keyof T)[];
+    debug?: boolean;
+};
+/** Query-specific props (default, scan is undefined or false) */
+type QueryFindProps<T extends object = Record<string, unknown>> = BaseFindProps<T> & {
+    /** Use Scan instead of Query (default: false) */
+    scan?: false | undefined;
+    /** Primary key condition (required for Query) */
+    pk: {
+        key?: string;
+        value: string;
+    };
+    /** Sort key condition (optional) */
+    sk?: SkCond;
+    /** Global secondary index name (optional) */
+    indexName?: string;
+    /** Sort order: ascending or descending (default: asc). Only available for Query. */
+    sort?: "asc" | "desc";
+};
+/** Scan-specific props (scan: true) */
+type ScanFindProps<T extends object = Record<string, unknown>> = BaseFindProps<T> & {
+    /** Use Scan instead of Query - scans entire table with optional filters */
+    scan: true;
+    /** pk is not allowed in scan mode - use filters instead */
+    pk?: never;
+    /** sk is not allowed in scan mode - use filters instead */
+    sk?: never;
+    /** Index to scan (optional, rarely needed for scans) */
+    indexName?: string;
+    /** sort is not available for Scan - DynamoDB returns items in storage order */
+    sort?: never;
+};
+/**
+ * Find props - discriminated union between Query and Scan modes
+ *
+ * @example
+ * // Query mode (default) - pk required
+ * const items = await find<User>(doc, {
+ *   tableName: 'users',
+ *   pk: { value: 'user#123' },
+ *   sk: { op: 'begins_with', value: 'profile#' },
+ *   sort: 'desc',
+ * });
+ *
+ * @example
+ * // Scan mode - no pk/sk, can filter on any attribute
+ * const items = await find<User>(doc, {
+ *   tableName: 'users',
+ *   scan: true,
+ *   filters: [
+ *     { key: 'pk', op: 'begins_with', value: 'user#' },
+ *     { key: 'status', op: '=', value: 'active' },
+ *   ],
+ * });
+ */
+export type FindProps<T extends object = Record<string, unknown>> = QueryFindProps<T> | ScanFindProps<T>;
+export type BatchGetResult<T> = {
+    items: T[];
+    count: number;
+    missing: number;
+    consumedCapacity?: number | undefined;
+};
+export type BatchWriteResult = {
+    processed: number;
+    failed: number;
+    consumedCapacity?: number | undefined;
+};
+export type BatchDeleteResult = {
+    processed: number;
+    failed: number;
+    consumedCapacity?: number | undefined;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/server/aws/ddb/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/aws/ddb/types.ts"],"names":[],"mappings":"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"}