@jaypie/dynamodb 0.1.3 → 0.2.0

package/dist/esm/queries.d.ts

@@ -1,4 +1,4 @@
-import type { BaseQueryOptions, FabricEntity, QueryResult } from "./types.js";
+import type { BaseQueryOptions, StorableEntity, QueryResult } from "./types.js";
 /**
  * Query parameters for queryByOu
  */
@@ -13,12 +13,12 @@ interface QueryByOuParams extends BaseQueryOptions {
  * Note: This is a regular async function (not serviceHandler) because it accepts
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-export declare function queryByOu({ archived, ascending, deleted, limit, model, ou, startKey, }: QueryByOuParams): Promise<QueryResult<FabricEntity>>;
+export declare function queryByOu({ archived, ascending, deleted, limit, model, ou, startKey, }: QueryByOuParams): Promise<QueryResult<StorableEntity>>;
 /**
  * Query a single entity by human-friendly alias
  * Uses indexAlias GSI
  */
-export declare const queryByAlias: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, FabricEntity | null>;
+export declare const queryByAlias: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, StorableEntity | null>;
 /**
  * Query parameters for queryByClass
  */
@@ -34,7 +34,7 @@ interface QueryByClassParams extends BaseQueryOptions {
  * Note: This is a regular async function (not serviceHandler) because it accepts
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-export declare function queryByClass({ archived, ascending, deleted, limit, model, ou, recordClass, startKey, }: QueryByClassParams): Promise<QueryResult<FabricEntity>>;
+export declare function queryByClass({ archived, ascending, deleted, limit, model, ou, recordClass, startKey, }: QueryByClassParams): Promise<QueryResult<StorableEntity>>;
 /**
  * Query parameters for queryByType
  */
@@ -50,10 +50,10 @@ interface QueryByTypeParams extends BaseQueryOptions {
  * Note: This is a regular async function (not serviceHandler) because it accepts
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-export declare function queryByType({ archived, ascending, deleted, limit, model, ou, startKey, type, }: QueryByTypeParams): Promise<QueryResult<FabricEntity>>;
+export declare function queryByType({ archived, ascending, deleted, limit, model, ou, startKey, type, }: QueryByTypeParams): Promise<QueryResult<StorableEntity>>;
 /**
  * Query a single entity by external ID
  * Uses indexXid GSI
  */
-export declare const queryByXid: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, FabricEntity | null>;
+export declare const queryByXid: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, StorableEntity | null>;
 export {};

package/dist/esm/query.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Unified Query Function with Auto-Detect Index Selection
+ *
+ * The query() function automatically selects the best index based on
+ * the filter fields provided. This simplifies query construction by
+ * removing the need to know which specific GSI to use.
+ */
+import { DEFAULT_INDEXES, getModelIndexes } from "@jaypie/vocabulary";
+import type { QueryResult, StorableEntity } from "./types.js";
+/**
+ * Query parameters for the unified query function
+ */
+export interface QueryParams<T = StorableEntity> {
+    /** Whether to query archived entities instead of active ones */
+    archived?: boolean;
+    /** Whether to sort ascending (oldest first). Default: false */
+    ascending?: boolean;
+    /** Whether to query deleted entities instead of active ones */
+    deleted?: boolean;
+    /** Filter object with field values to match. Used for index auto-detection. */
+    filter?: Partial<T>;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Model name (required) */
+    model: string;
+    /** Organizational unit (APEX or "{parent.model}#{parent.id}") */
+    ou?: string;
+    /** Pagination cursor from previous query */
+    startKey?: Record<string, unknown>;
+}
+/**
+ * Query entities with automatic index selection
+ *
+ * The query function automatically selects the best GSI based on
+ * the filter fields provided. This removes the need to know which
+ * specific query function (queryByOu, queryByAlias, etc.) to use.
+ *
+ * @example
+ * // Uses indexOu (pk: ["ou", "model"])
+ * const allMessages = await query({ model: "message", ou: `chat#${chatId}` });
+ *
+ * @example
+ * // Uses indexAlias (pk: ["ou", "model", "alias"])
+ * const byAlias = await query({
+ *   model: "record",
+ *   ou: "@",
+ *   filter: { alias: "my-record" },
+ * });
+ *
+ * @example
+ * // Uses a custom registered index if model has one
+ * const byChat = await query({
+ *   model: "message",
+ *   filter: { chatId: "abc-123" },
+ * });
+ */
+export declare function query<T extends StorableEntity = StorableEntity>(params: QueryParams<T>): Promise<QueryResult<T>>;
+export { DEFAULT_INDEXES, getModelIndexes };

package/dist/esm/seedExport.d.ts

@@ -1,4 +1,4 @@
-import type { FabricEntity } from "./types.js";
+import type { StorableEntity } from "./types.js";
 /**
  * Result of a seed operation
  */
@@ -25,7 +25,7 @@ export interface SeedOptions {
 /**
  * Result of an export operation
  */
-export interface ExportResult<T extends FabricEntity = FabricEntity> {
+export interface ExportResult<T extends StorableEntity = StorableEntity> {
     /** Number of entities exported */
     count: number;
     /** Exported entities */
@@ -37,7 +37,7 @@ export interface ExportResult<T extends FabricEntity = FabricEntity> {
  * @param entity - Partial entity with at least alias, model, and ou
  * @returns true if entity was created, false if it already exists
  */
-export declare function seedEntityIfNotExists<T extends Partial<FabricEntity>>(entity: T): Promise<boolean>;
+export declare function seedEntityIfNotExists<T extends Partial<StorableEntity>>(entity: T): Promise<boolean>;
 /**
  * Seed multiple entities (idempotent)
  *
@@ -50,7 +50,7 @@ export declare function seedEntityIfNotExists<T extends Partial<FabricEntity>>(e
  * @param options - Seed options
  * @returns Result with created, skipped, and errors arrays
  */
-export declare function seedEntities<T extends Partial<FabricEntity>>(entities: T[], options?: SeedOptions): Promise<SeedResult>;
+export declare function seedEntities<T extends Partial<StorableEntity>>(entities: T[], options?: SeedOptions): Promise<SeedResult>;
 /**
  * Export entities by model and organizational unit
  *
@@ -62,7 +62,7 @@ export declare function seedEntities<T extends Partial<FabricEntity>>(entities:
  * @param limit - Optional maximum number of entities to export
  * @returns Export result with entities and count
  */
-export declare function exportEntities<T extends FabricEntity>(model: string, ou: string, limit?: number): Promise<ExportResult<T>>;
+export declare function exportEntities<T extends StorableEntity>(model: string, ou: string, limit?: number): Promise<ExportResult<T>>;
 /**
  * Export entities as a JSON string
  *

package/dist/esm/types.d.ts

@@ -1,3 +1,4 @@
+import type { BaseEntity } from "@jaypie/vocabulary";
 /**
  * DynamoDB client configuration
  */
@@ -100,16 +101,21 @@ export interface QueryByXidParams {
 /**
  * Result of a query operation
  */
-export interface QueryResult<T = FabricEntity> {
+export interface QueryResult<T = StorableEntity> {
     /** Array of matching entities */
     items: T[];
     /** Pagination cursor for next page (undefined if no more results) */
     lastEvaluatedKey?: Record<string, unknown>;
 }
 /**
- * Base entity interface for DynamoDB single-table design
+ * Entity with required fields for DynamoDB storage.
+ *
+ * Extends BaseEntity from @jaypie/vocabulary with:
+ * - Required storage fields (id, model, name, ou, sequence)
+ * - String timestamps (DynamoDB uses ISO 8601 strings, not Date objects)
+ * - GSI index keys (auto-populated by indexEntity)
  */
-export interface FabricEntity {
+export interface StorableEntity extends Omit<BaseEntity, "archivedAt" | "createdAt" | "deletedAt" | "updatedAt"> {
     /** Partition key (e.g., "record", "message") */
     model: string;
     /** Sort key (UUID) */
@@ -125,14 +131,6 @@ export interface FabricEntity {
     indexOu?: string;
     indexType?: string;
     indexXid?: string;
-    /** Human-friendly slug/alias */
-    alias?: string;
-    /** Category classification */
-    class?: string;
-    /** Type classification */
-    type?: string;
-    /** External ID for integration with external systems */
-    xid?: string;
     createdAt: string;
     updatedAt: string;
     /** Archive timestamp (for inactive but preserved records) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/dynamodb",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/finlaysonstudio/jaypie.git"
@@ -41,7 +41,7 @@
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.726.1",
     "@aws-sdk/lib-dynamodb": "^3.726.1",
-    "@jaypie/vocabulary": "^0.1.7"
+    "@jaypie/vocabulary": "^0.2.0"
   },
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.1.2",