electrodb 2.15.0 → 3.0.1

package/README.md

@@ -16,15 +16,19 @@
 
 _Please submit issues/feedback or reach out on Twitter [@tinkertamper](https://twitter.com/tinkertamper)._
 
+<a href="https://electrodb.dev/en/core-concepts/v3-migration/"><h1 align="center">ElectroDB v3 now released</h1></a>
+
+<p align="center">Visit the <a href="https://electrodb.dev/en/core-concepts/v3-migration/">v3 migration page</a> to learn more about this new update.</p>
+
 ---
 
-<a href="https://electrodb.dev"><h1 align="center">New: Documentation now found at ElectroDB.dev</h1></a>
+<a href="https://electrodb.dev"><h1 align="center">Documentation now found at ElectroDB.dev</h1></a>
 
-<p align="center">ElectroDB's new website for Documentation is now live at <a href="https://electrodb.dev">www.ElectroDB.dev</a>.</p>
+<p align="center">ElectroDB's new website for Documentation is now live at <a href="https://electrodb.dev">electrodb.dev</a>.</p>
 
 ---
 
-<a href="https://electrodb.fun"><h1 align="center">Introducing: The NEW ElectroDB Playground</h1></a>
+<a href="https://electrodb.fun"><h1 align="center">The NEW ElectroDB Playground</h1></a>
 
 <p align="center">
   <a href="https://electrodb.fun"><img width="400" src="https://github.com/tywalch/electrodb/blob/master/assets/playground.jpg?raw=true"></a>

package/index.d.ts

@@ -2536,12 +2536,9 @@ export interface QueryOptions {
   listeners?: Array<ElectroEventListener>;
   logger?: ElectroEventListener;
   data?: "raw" | "includeKeys" | "attributes";
-
-  /** @depricated use 'data=raw' instead */
-  raw?: boolean;
-  /** @depricated use 'data=includeKeys' instead */
-  includeKeys?: boolean;
   order?: "asc" | "desc";
+
+  consistent?: boolean;
 }
 
 // subset of QueryOptions
@@ -2581,7 +2578,7 @@ export interface PutQueryOptions extends QueryOptions {
   response?: "default" | "none" | "all_old" | "all_new";
 }
 
-export interface ParamOptions {
+export type ParamOptions = {
   cursor?: string | null;
   params?: object;
   table?: string;
@@ -2594,7 +2591,8 @@ export interface ParamOptions {
     | "all_new"
     | "updated_new";
   order?: "asc" | "desc";
-}
+  consistent?: boolean;
+} & QueryExecutionComparisonParts;
 
 export interface BulkOptions extends QueryOptions {
   unprocessed?: "raw" | "item";
@@ -2609,11 +2607,6 @@ export type OptionalDefaultEntityIdentifiers = {
 
 interface GoBatchGetTerminalOptions<Attributes> {
   data?: "raw" | "includeKeys" | "attributes";
-  /** @depricated use 'data=raw' instead */
-  raw?: boolean;
-  /** @depricated use 'data=raw' instead */
-  includeKeys?: boolean;
-
   table?: string;
   limit?: number;
   params?: object;
@@ -2626,15 +2619,23 @@ interface GoBatchGetTerminalOptions<Attributes> {
   preserveBatchOrder?: boolean;
   listeners?: Array<ElectroEventListener>;
   logger?: ElectroEventListener;
+  consistent?: boolean;
 }
 
-interface ServiceQueryGoTerminalOptions {
+export type ExecutionOptionCompare = "keys" | "attributes" | "v2";
+
+export type QueryExecutionComparisonParts = {
+  compare?: "keys" | "attributes"
+} | {
+  /**
+   * @deprecated 'v2' exists to ease user migration to ElectroDB v3. Support for this option will eventually be dropped.
+   */
+  compare?: "v2"
+}
+
+type ServiceQueryGoTerminalOptions = {
   cursor?: string | null;
   data?: "raw" | "includeKeys" | "attributes";
-  /** @depricated use 'data=raw' instead */
-  raw?: boolean;
-  /** @depricated use 'data=raw' instead */
-  includeKeys?: boolean;
   table?: string;
   limit?: number;
   params?: object;
@@ -2645,15 +2646,12 @@ interface ServiceQueryGoTerminalOptions {
   logger?: ElectroEventListener;
   order?: "asc" | "desc";
   hydrate?: boolean;
-}
+  consistent?: boolean;
+} & QueryExecutionComparisonParts;
 
-interface GoQueryTerminalOptions<Attributes> {
+type GoQueryTerminalOptions<Attributes> = {
   cursor?: string | null;
   data?: "raw" | "includeKeys" | "attributes";
-  /** @depricated use 'data=raw' instead */
-  raw?: boolean;
-  /** @depricated use 'data=raw' instead */
-  includeKeys?: boolean;
   table?: string;
   limit?: number;
   count?: number;
@@ -2666,7 +2664,8 @@ interface GoQueryTerminalOptions<Attributes> {
   logger?: ElectroEventListener;
   order?: "asc" | "desc";
   hydrate?: boolean;
-}
+  consistent?: boolean;
+} & QueryExecutionComparisonParts;
 
 interface TransactWriteQueryOptions {
   data?: "raw" | "includeKeys" | "attributes";
@@ -2688,13 +2687,15 @@ interface TransactGetQueryOptions<Attributes> {
   attributes?: ReadonlyArray<Attributes>;
   listeners?: Array<ElectroEventListener>;
   logger?: ElectroEventListener;
+  consistent?: boolean;
 }
 
-export interface ParamTerminalOptions<Attributes> {
+export type ParamTerminalOptions<Attributes> = {
   table?: string;
   limit?: number;
   params?: object;
   originalErr?: boolean;
+  consistent?: boolean;
   attributes?: ReadonlyArray<Attributes>;
   response?:
     | "default"
@@ -2704,7 +2705,7 @@ export interface ParamTerminalOptions<Attributes> {
     | "all_new"
     | "updated_new";
   order?: "asc" | "desc";
-}
+} & QueryExecutionComparisonParts;
 
 type GoBatchGetTerminal<
   A extends string,
@@ -2912,16 +2913,14 @@ export type DeleteRecordOperationGo<ResponseType, Keys> = <
   options?: Options,
 ) => Options extends infer O
   ? "response" extends keyof O
-    ? O["response"] extends "all_new"
-      ? Promise<{ data: T }>
-      : O["response"] extends "all_old"
-      ? Promise<{ data: T }>
+    ? O["response"] extends "all_old"
+      ? Promise<{ data: T | null }>
       : O["response"] extends "default"
-      ? Promise<{ data: Keys }>
-      : O["response"] extends "none"
-      ? Promise<{ data: null }>
-      : Promise<{ data: Partial<T> }>
-    : Promise<{ data: Keys }>
+        ? Promise<{ data: Keys }>
+        : O["response"] extends "none"
+          ? Promise<{ data: null }>
+          : Promise<{ data: Keys | null }>
+    : Promise<{ data: Keys  }>
   : never;
 
 export type BatchWriteGo<ResponseType> = <O extends BulkOptions>(
@@ -3002,10 +3001,7 @@ export interface NestedBooleanAttribute {
   readonly get?: (val: boolean, item: any) => boolean | undefined | void;
   readonly set?: (val?: boolean, item?: any) => boolean | undefined | void;
   readonly default?: boolean | (() => boolean);
-  readonly validate?:
-    | ((val: boolean) => boolean)
-    | ((val: boolean) => void)
-    | ((val: boolean) => string | void);
+  readonly validate?: ((val: boolean) => boolean)
   readonly field?: string;
 }
 
@@ -3017,10 +3013,7 @@ export interface BooleanAttribute {
   readonly get?: (val: boolean, item: any) => boolean | undefined | void;
   readonly set?: (val?: boolean, item?: any) => boolean | undefined | void;
   readonly default?: boolean | (() => boolean);
-  readonly validate?:
-    | ((val: boolean) => boolean)
-    | ((val: boolean) => void)
-    | ((val: boolean) => string | void);
+  readonly validate?: ((val: boolean) => boolean)
   readonly field?: string;
   readonly label?: string;
   readonly watch?: ReadonlyArray<string> | "*";
@@ -3038,10 +3031,7 @@ export interface NestedNumberAttribute {
   readonly get?: (val: number, item: any) => number | undefined | void;
   readonly set?: (val?: number, item?: any) => number | undefined | void;
   readonly default?: number | (() => number);
-  readonly validate?:
-    | ((val: number) => boolean)
-    | ((val: number) => void)
-    | ((val: number) => string | void);
+  readonly validate?: ((val: number) => boolean)
   readonly field?: string;
 }
 
@@ -3053,10 +3043,7 @@ export interface NumberAttribute {
   readonly get?: (val: number, item: any) => number | undefined | void;
   readonly set?: (val?: number, item?: any) => number | undefined | void;
   readonly default?: number | (() => number);
-  readonly validate?:
-    | ((val: number) => boolean)
-    | ((val: number) => void)
-    | ((val: number) => string | void);
+  readonly validate?: ((val: number) => boolean)
   readonly field?: string;
   readonly label?: string;
   readonly watch?: ReadonlyArray<string> | "*";
@@ -3076,8 +3063,6 @@ export interface NestedStringAttribute {
   readonly default?: string | (() => string);
   readonly validate?:
     | ((val: string) => boolean)
-    | ((val: string) => void)
-    | ((val: string) => string | void)
     | RegExp;
   readonly field?: string;
 }
@@ -3092,8 +3077,6 @@ export interface StringAttribute {
   readonly default?: string | (() => string);
   readonly validate?:
     | ((val: string) => boolean)
-    | ((val: string) => void)
-    | ((val: string) => string | void)
     | RegExp;
   readonly field?: string;
   readonly label?: string;
@@ -3112,10 +3095,7 @@ export interface NestedEnumAttribute {
   readonly get?: (val: any, item: any) => any | undefined | void;
   readonly set?: (val?: any, item?: any) => any | undefined | void;
   readonly default?: string | (() => string);
-  readonly validate?:
-    | ((val: any) => boolean)
-    | ((val: any) => void)
-    | ((val: any) => string | void);
+  readonly validate?: ((val: any) => boolean)
   readonly field?: string;
   readonly label?: string;
 }
@@ -3128,10 +3108,7 @@ export interface EnumAttribute {
   readonly get?: (val: any, item: any) => any | undefined | void;
   readonly set?: (val?: any, item?: any) => any | undefined | void;
   readonly default?: string | (() => string);
-  readonly validate?:
-    | ((val: any) => boolean)
-    | ((val: any) => void)
-    | ((val: any) => string | void);
+  readonly validate?: ((val: any) => boolean)
   readonly field?: string;
   readonly label?: string;
   readonly watch?: ReadonlyArray<string> | "*";
@@ -3145,10 +3122,7 @@ export interface NestedAnyAttribute {
   readonly get?: (val: any, item: any) => any | undefined | void;
   readonly set?: (val?: any, item?: any) => any | undefined | void;
   readonly default?: any | (() => any);
-  readonly validate?:
-    | ((val: any) => boolean)
-    | ((val: any) => void)
-    | ((val: any) => string | void);
+  readonly validate?: ((val: any) => boolean)
   readonly field?: string;
 }
 
@@ -3160,10 +3134,7 @@ export interface AnyAttribute {
   readonly get?: (val: any, item: any) => any | undefined | void;
   readonly set?: (val?: any, item?: any) => any | undefined | void;
   readonly default?: any | (() => any);
-  readonly validate?:
-    | ((val: any) => boolean)
-    | ((val: any) => void)
-    | ((val: any) => string | void);
+  readonly validate?: ((val: any) => boolean)
   readonly field?: string;
   readonly label?: string;
   readonly watch?: ReadonlyArray<string> | "*";
@@ -3186,10 +3157,7 @@ export interface NestedMapAttribute {
     item?: any,
   ) => Record<string, any> | undefined | void;
   readonly default?: Record<string, any> | (() => Record<string, any>);
-  readonly validate?:
-    | ((val: Record<string, any>) => boolean)
-    | ((val: Record<string, any>) => void)
-    | ((val: Record<string, any>) => string | void);
+  readonly validate?: ((val: Record<string, any>) => boolean)
   readonly field?: string;
 }
 
@@ -3210,10 +3178,7 @@ export interface MapAttribute {
     item?: any,
   ) => Record<string, any> | undefined | void;
   readonly default?: Record<string, any> | (() => Record<string, any>);
-  readonly validate?:
-    | ((val: Record<string, any>) => boolean)
-    | ((val: Record<string, any>) => void)
-    | ((val: Record<string, any>) => string | void);
+  readonly validate?: ((val: Record<string, any>) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3233,10 +3198,7 @@ export interface NestedCustomListAttribute {
       item?: any,
   ) => Array<any> | undefined | void;
   readonly default?: Array<any> | (() => Array<any>);
-  readonly validate?:
-      | ((val: Array<any>) => boolean)
-      | ((val: Array<any>) => void)
-      | ((val: Array<any>) => string | void);
+  readonly validate?: ((val: Array<any>) => boolean)
 }
 
 export interface NestedStringListAttribute {
@@ -3251,8 +3213,6 @@ export interface NestedStringListAttribute {
     readonly default?: string | (() => string);
     readonly validate?:
       | ((val: string) => boolean)
-      | ((val: string) => void)
-      | ((val: string) => string | void)
       | RegExp;
     readonly field?: string;
   };
@@ -3268,10 +3228,7 @@ export interface NestedStringListAttribute {
     item?: any,
   ) => Array<string> | undefined | void;
   readonly default?: Array<string> | (() => Array<string>);
-  readonly validate?:
-    | ((val: Array<string>) => boolean)
-    | ((val: Array<string>) => void)
-    | ((val: Array<string>) => string | void);
+  readonly validate?: ((val: Array<string>) => boolean)
 }
 
 export interface StringListAttribute {
@@ -3286,8 +3243,6 @@ export interface StringListAttribute {
     readonly default?: string | (() => string);
     readonly validate?:
       | ((val: string) => boolean)
-      | ((val: string) => void)
-      | ((val: string) => string | void)
       | RegExp;
     readonly field?: string;
   };
@@ -3303,10 +3258,7 @@ export interface StringListAttribute {
     item?: any,
   ) => Array<string> | undefined | void;
   readonly default?: Array<string> | (() => Array<string>);
-  readonly validate?:
-    | ((val: Array<string>) => boolean)
-    | ((val: Array<string>) => void)
-    | ((val: Array<string>) => string | void);
+  readonly validate?: ((val: Array<string>) => boolean)
   readonly watch?: ReadonlyArray<string> | "*";
 }
 
@@ -3325,10 +3277,7 @@ export interface NestedNumberListAttribute {
     item?: any,
   ) => Array<number> | undefined | void;
   readonly default?: Array<number> | (() => Array<number>);
-  readonly validate?:
-    | ((val: Array<number>) => boolean)
-    | ((val: Array<number>) => void)
-    | ((val: Array<number>) => string | void);
+  readonly validate?: ((val: Array<number>) => boolean)
   readonly field?: string;
 }
 
@@ -3347,10 +3296,7 @@ export interface NumberListAttribute {
     item?: any,
   ) => Array<number> | undefined | void;
   readonly default?: Array<number> | (() => Array<number>);
-  readonly validate?:
-    | ((val: Array<number>) => boolean)
-    | ((val: Array<number>) => void)
-    | ((val: Array<number>) => string | void);
+  readonly validate?: ((val: Array<number>) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3370,10 +3316,7 @@ export interface NestedMapListAttribute {
     item?: any,
   ) => Record<string, any>[] | undefined | void;
   readonly default?: Record<string, any>[] | (() => Record<string, any>[]);
-  readonly validate?:
-    | ((val: Record<string, any>[]) => boolean)
-    | ((val: Record<string, any>[]) => void)
-    | ((val: Record<string, any>[]) => string | void);
+  readonly validate?: ((val: Record<string, any>[]) => boolean)
   readonly field?: string;
 }
 
@@ -3392,10 +3335,7 @@ export interface NestedAnyListAttribute {
       item?: any,
   ) => Record<string, any>[] | undefined | void;
   readonly default?: Record<string, any>[] | (() => Record<string, any>[]);
-  readonly validate?:
-      | ((val: Record<string, any>[]) => boolean)
-      | ((val: Record<string, any>[]) => void)
-      | ((val: Record<string, any>[]) => string | void);
+  readonly validate?: ((val: Record<string, any>[]) => boolean)
   readonly field?: string;
 }
 
@@ -3414,10 +3354,7 @@ export interface MapListAttribute {
     item?: any,
   ) => Record<string, any>[] | undefined | void;
   readonly default?: Record<string, any>[] | (() => Record<string, any>[]);
-  readonly validate?:
-    | ((val: Record<string, any>[]) => boolean)
-    | ((val: Record<string, any>[]) => void)
-    | ((val: Record<string, any>[]) => string | void);
+  readonly validate?: ((val: Record<string, any>[]) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3437,10 +3374,7 @@ export interface CustomListAttribute {
       item?: any,
   ) => Array<any> | undefined | void;
   readonly default?: Array<any> | (() => Array<any>);
-  readonly validate?:
-      | ((val: Array<any>) => boolean)
-      | ((val: Array<any>) => void)
-      | ((val: Array<any>) => string | void);
+  readonly validate?: ((val: Array<any>) => boolean);
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3460,10 +3394,7 @@ export interface AnyListAttribute {
       item?: any,
   ) => Array<any> | undefined | void;
   readonly default?: Array<any> | (() => Array<any>);
-  readonly validate?:
-      | ((val: Array<any>) => boolean)
-      | ((val: Array<any>) => void)
-      | ((val: Array<any>) => string | void);
+  readonly validate?: ((val: Array<any>) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3485,8 +3416,6 @@ export interface NestedStringSetAttribute {
   readonly default?: Array<string> | (() => Array<string>);
   readonly validate?:
     | ((val: Array<string>) => boolean)
-    | ((val: Array<string>) => void)
-    | ((val: Array<string>) => string | void)
     | RegExp;
   readonly field?: string;
 }
@@ -3506,11 +3435,7 @@ export interface NestedEnumNumberSetAttribute {
     item?: any,
   ) => Array<number> | undefined | void;
   readonly default?: Array<number> | (() => Array<number>);
-  readonly validate?:
-    | ((val: Array<number>) => boolean)
-    | ((val: Array<number>) => void)
-    | ((val: Array<number>) => string | void)
-    | RegExp;
+  readonly validate?: ((val: Array<number>) => boolean)
   readonly field?: string;
 }
 
@@ -3529,11 +3454,7 @@ export interface EnumNumberSetAttribute {
     item?: any,
   ) => Array<number> | undefined | void;
   readonly default?: Array<number> | (() => Array<number>);
-  readonly validate?:
-    | ((val: Array<number>) => boolean)
-    | ((val: Array<number>) => void)
-    | ((val: Array<number>) => string | void)
-    | RegExp;
+  readonly validate?: ((val: Array<number>) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3555,8 +3476,6 @@ export interface NestedEnumStringSetAttribute {
   readonly default?: Array<string> | (() => Array<string>);
   readonly validate?:
     | ((val: Array<string>) => boolean)
-    | ((val: Array<string>) => void)
-    | ((val: Array<string>) => string | void)
     | RegExp;
   readonly field?: string;
 }
@@ -3578,8 +3497,6 @@ export interface EnumStringSetAttribute {
   readonly default?: Array<string> | (() => Array<string>);
   readonly validate?:
     | ((val: Array<string>) => boolean)
-    | ((val: Array<string>) => void)
-    | ((val: Array<string>) => string | void)
     | RegExp;
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
@@ -3602,8 +3519,6 @@ export interface StringSetAttribute {
   readonly default?: Array<string> | (() => Array<string>);
   readonly validate?:
     | ((val: Array<string>) => boolean)
-    | ((val: Array<string>) => void)
-    | ((val: Array<string>) => string | void)
     | RegExp;
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
@@ -3624,10 +3539,7 @@ export interface NestedNumberSetAttribute {
     item?: any,
   ) => Array<number> | undefined | void;
   readonly default?: Array<number> | (() => Array<number>);
-  readonly validate?:
-    | ((val: Array<number>) => boolean)
-    | ((val: Array<number>) => void)
-    | ((val: Array<number>) => string | void);
+  readonly validate?: ((val: Array<number>) => boolean)
   readonly field?: string;
 }
 
@@ -3646,10 +3558,7 @@ export interface NumberSetAttribute {
     item?: any,
   ) => Array<number> | undefined | void;
   readonly default?: Array<number> | (() => Array<number>);
-  readonly validate?:
-    | ((val: Array<number>) => boolean)
-    | ((val: Array<number>) => void)
-    | ((val: Array<number>) => string | void);
+  readonly validate?: ((val: Array<number>) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 }
@@ -3673,10 +3582,7 @@ type CustomAttribute = {
   readonly get?: (val: any, item: any) => any | undefined | void;
   readonly set?: (val?: any, item?: any) => any | undefined | void;
   readonly default?: any | (() => any);
-  readonly validate?:
-    | ((val: any) => boolean)
-    | ((val: any) => void)
-    | ((val: any) => string | void);
+  readonly validate?: ((val: any) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 };
@@ -3689,10 +3595,7 @@ type NestedCustomAttribute = {
   readonly get?: (val: any, item: any) => any | undefined | void;
   readonly set?: (val?: any, item?: any) => any | undefined | void;
   readonly default?: any | (() => any);
-  readonly validate?:
-      | ((val: any) => boolean)
-      | ((val: any) => void)
-      | ((val: any) => string | void);
+  readonly validate?: ((val: any) => boolean)
   readonly field?: string;
 };
 
@@ -5367,7 +5270,6 @@ export class Entity<
     TableIndexCompositeAttributes<A, F, C, S>
   >;
   query: Queries<A, F, C, S>;
-  conversions: Conversions<A, F, C, S>;
 
   parse<Options extends ParseOptions<keyof ResponseItem<A, F, C, S>>>(
     item: ParseSingleInput,
@@ -5404,6 +5306,13 @@ export class Entity<
   client: any;
 }
 
+declare function createConversions<
+  A extends string,
+  F extends string,
+  C extends string,
+  S extends Schema<A, F, C>,
+>(entity: Entity<A,F,C,S>): Conversions<A, F, C, S>;
+
 export class TransactWriteEntity<
   A extends string,
   F extends string,
@@ -5778,10 +5687,7 @@ type CustomAttributeDefinition<T> = {
   readonly get?: (val: T, item: any) => T | undefined | void;
   readonly set?: (val?: T, item?: any) => T | undefined | void;
   readonly default?: T | (() => T);
-  readonly validate?:
-    | ((val: T) => boolean)
-    | ((val: T) => void)
-    | ((val: T) => string | void);
+  readonly validate?: ((val: T) => boolean)
   readonly field?: string;
   readonly watch?: ReadonlyArray<string> | "*";
 };
@@ -5811,4 +5717,4 @@ declare function createSchema<
   F extends string,
   C extends string,
   S extends Schema<A, F, C>,
->(schema: S): S;
+>(schema: S): S;

package/index.js

@@ -15,15 +15,24 @@ const {
   ElectroUserValidationError,
   ElectroAttributeValidationError,
 } = require("./src/errors");
+const { createConversions } = require("./src/conversions");
+
+const {
+  ComparisonTypes
+} = require('./src/types');
 
 module.exports = {
   Entity,
   Service,
   ElectroError,
   createSchema,
+  ComparisonTypes,
   CustomAttributeType,
   createCustomAttribute,
   ElectroValidationError,
   createGetTransaction,
   createWriteTransaction,
+  ElectroUserValidationError,
+  ElectroAttributeValidationError,
+  createConversions,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrodb",
-  "version": "2.15.0",
+  "version": "3.0.1",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {