electrodb 1.10.2 → 1.11.0

package/README.md

@@ -2607,9 +2607,10 @@ const formattedQueryResults = myEntity.parse(formattedQueryResults);
 
 Parse also accepts an optional `options` object as a second argument (see the section [Query Options](#query-options) to learn more). Currently, the following query options are relevant to the `parse()` method:
 
-Option            | Default | Notes
------------------ : ------- | -----
-`ignoreOwnership` | `true`  | This property defaults to `true` here, unlike elsewhere in the application when it defaults to `false`. You can overwrite the default here with your own preference. 
+Option            | Type     | Default            | Notes
+----------------- : -------- : ------------------ | -----
+ignoreOwnership   | boolean  | `true`             | This property defaults to `true` here, unlike elsewhere in the application when it defaults to `false`. You can overwrite the default here with your own preference.
+attributes        | string[] | _(all attributes)_ | The `attributes` option allows you to specify a subset of attributes to return
 
 # Building Queries
 > For hands-on learners: the following example can be followed along with **and** executed on runkit: https://runkit.com/tywalch/electrodb-building-queries
@@ -4300,6 +4301,7 @@ By default, **ElectroDB** enables you to work with records as the names and prop
   logger?: (event) => void;
   listeners Array<(event) => void>;
   preserveBatchOrder?: boolean;
+  attributes?: string[];
 };
 ```
 
@@ -4307,6 +4309,7 @@ Option             | Default              | Description
 ------------------ | :------------------: | -----------
 params             | `{}`                 | Properties added to this object will be merged onto the params sent to the document client. Any conflicts with **ElectroDB** will favor the params specified here.
 table              | _(from constructor)_ | Use a different table than the one defined in the [Service Options](#service-options)
+attributes         | _(all attributes)_   | The `attributes` query option allows you to specify ProjectionExpression Attributes for your `get` or `query` operation. As of `1.11.0` only root attributes are allowed to be specified.
 raw                | `false`              | Returns query results as they were returned by the docClient.
 includeKeys        | `false`              | By default, **ElectroDB** does not return partition, sort, or global keys in its response.
 pager              | `"named"`            | Used in with pagination (`.pages()`) calls to override ElectroDBs default behaviour to break apart `LastEvaluatedKeys` records into composite attributes. See more detail about this in the sections for [Pager Query Options](#pager-query-options).

package/index.d.ts

@@ -79,6 +79,7 @@ export type CollectionWhereCallback<E extends {[name: string]: Entity<any, any,
 
 export type CollectionWhereClause<E extends {[name: string]: Entity<any, any, any, any>}, A extends string, F extends string, C extends string, S extends Schema<A,F,C>, I extends Partial<AllEntityAttributes<E>>, T> = (where: CollectionWhereCallback<E, I>) => T;
 
+
 export interface WhereRecordsActionOptions<E extends {[name: string]: Entity<any, any, any, any>}, A extends string, F extends string, C extends string, S extends Schema<A,F,C>, I extends Partial<AllEntityAttributes<E>>, Items, IndexCompositeAttributes> {
     go: GoRecord<Items>;
     params: ParamRecord;
@@ -349,6 +350,13 @@ export type CollectionItem<SERVICE extends Service<any>, COLLECTION extends keyo
         : never>
         : never
 
+export interface QueryBranches<A extends string,
+    F extends string, C extends string, S extends Schema<A,F,C>, ResponseItem, IndexCompositeAttributes> {
+    go: GoQueryTerminal<A,F,C,S,ResponseItem>;
+    params: ParamTerminal<A,F,C,S,ResponseItem>;
+    page: PageQueryTerminal<A,F,C,S,ResponseItem,IndexCompositeAttributes>;
+    where: WhereClause<A,F,C,S,Item<A,F,C,S,S["attributes"]>,QueryBranches<A,F,C,S,ResponseItem,IndexCompositeAttributes>>
+}
 
 export interface RecordsActionOptions<A extends string,
     F extends string, C extends string, S extends Schema<A,F,C>, Items, IndexCompositeAttributes> {
@@ -359,11 +367,16 @@ export interface RecordsActionOptions<A extends string,
 }
 
 export interface SingleRecordOperationOptions<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseType> {
-    go: GoRecord<ResponseType, QueryOptions>;
-    params: ParamRecord<QueryOptions>;
+    go: GoGetTerminal<A,F,C,S, ResponseType>;
+    params: ParamTerminal<A,F,C,S,ResponseType>;
     where: WhereClause<A,F,C,S,Item<A,F,C,S,S["attributes"]>,SingleRecordOperationOptions<A,F,C,S,ResponseType>>;
 }
 
+export interface BatchGetRecordOperationOptions<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseType> {
+    go: GoBatchGetTerminal<A,F,C,S,ResponseType>
+    params: ParamTerminal<A,F,C,S,ResponseType>;
+}
+
 export interface PutRecordOperationOptions<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseType> {
     go: GoRecord<ResponseType, PutQueryOptions>;
     params: ParamRecord<PutQueryOptions>;
@@ -406,17 +419,17 @@ export type RemoveRecord<A extends string, F extends string, C extends string, S
 export type DataUpdateMethodRecord<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, SetAttr, IndexCompositeAttributes, TableItem> =
     DataUpdateMethod<A,F,C,S, UpdateData<A,F,C,S>, SetRecordActionOptions<A,F,C,S, SetAttr, IndexCompositeAttributes, TableItem>>
 
-interface QueryOperations<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, CompositeAttributes, TableItem, IndexCompositeAttributes> {
-    between: (skCompositeAttributesStart: CompositeAttributes, skCompositeAttributesEnd: CompositeAttributes) => RecordsActionOptions<A,F,C,S, Array<TableItem>,IndexCompositeAttributes>;
-    gt: (skCompositeAttributes: CompositeAttributes) => RecordsActionOptions<A,F,C,S, Array<TableItem>,IndexCompositeAttributes>;
-    gte: (skCompositeAttributes: CompositeAttributes) => RecordsActionOptions<A,F,C,S, Array<TableItem>,IndexCompositeAttributes>;
-    lt: (skCompositeAttributes: CompositeAttributes) => RecordsActionOptions<A,F,C,S, Array<TableItem>,IndexCompositeAttributes>;
-    lte: (skCompositeAttributes: CompositeAttributes) => RecordsActionOptions<A,F,C,S, Array<TableItem>,IndexCompositeAttributes>;
-    begins: (skCompositeAttributes: CompositeAttributes) => RecordsActionOptions<A,F,C,S, Array<TableItem>,IndexCompositeAttributes>;
-    go: GoRecord<Array<TableItem>>;
-    params: ParamRecord;
-    page: PageRecord<Array<TableItem>,IndexCompositeAttributes>;
-    where: WhereClause<A,F,C,S,Item<A,F,C,S,S["attributes"]>,RecordsActionOptions<A,F,C,S,Array<TableItem>,IndexCompositeAttributes>>
+interface QueryOperations<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, CompositeAttributes, ResponseItem, IndexCompositeAttributes> {
+    between: (skCompositeAttributesStart: CompositeAttributes, skCompositeAttributesEnd: CompositeAttributes) => QueryBranches<A,F,C,S, ResponseItem, IndexCompositeAttributes>;
+    gt: (skCompositeAttributes: CompositeAttributes) => QueryBranches<A,F,C,S, ResponseItem,IndexCompositeAttributes>;
+    gte: (skCompositeAttributes: CompositeAttributes) => QueryBranches<A,F,C,S, ResponseItem,IndexCompositeAttributes>;
+    lt: (skCompositeAttributes: CompositeAttributes) => QueryBranches<A,F,C,S, ResponseItem,IndexCompositeAttributes>;
+    lte: (skCompositeAttributes: CompositeAttributes) => QueryBranches<A,F,C,S, ResponseItem,IndexCompositeAttributes>;
+    begins: (skCompositeAttributes: CompositeAttributes) => QueryBranches<A,F,C,S, ResponseItem,IndexCompositeAttributes>;
+    go: GoQueryTerminal<A,F,C,S,ResponseItem>;
+    params: ParamTerminal<A,F,C,S,ResponseItem>;
+    page: PageQueryTerminal<A,F,C,S,ResponseItem,IndexCompositeAttributes>;
+    where: WhereClause<A,F,C,S,Item<A,F,C,S,S["attributes"]>,QueryBranches<A,F,C,S,ResponseItem,IndexCompositeAttributes>>
 }
 
 export type Queries<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
@@ -424,7 +437,7 @@ export type Queries<A extends string, F extends string, C extends string, S exte
         IndexSKAttributes<A,F,C,S,I> extends infer SK
             // If there is no SK, dont show query operations (when an empty array is provided)
             ? [keyof SK] extends [never]
-            ? RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S> & Required<CompositeAttributes>>
+            ? QueryBranches<A,F,C,S, ResponseItem<A,F,C,S>, AllTableIndexCompositeAttributes<A,F,C,S> & Required<CompositeAttributes>>
             // If there is no SK, dont show query operations (When no PK is specified)
             : S["indexes"][I] extends IndexWithSortKey
                 ? QueryOperations<
@@ -434,7 +447,7 @@ export type Queries<A extends string, F extends string, C extends string, S exte
                     ResponseItem<A,F,C,S>,
                     AllTableIndexCompositeAttributes<A,F,C,S> & Required<CompositeAttributes> & SK
                     >
-                : RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S> & Required<CompositeAttributes> & SK>
+                : QueryBranches<A,F,C,S, ResponseItem<A,F,C,S>, AllTableIndexCompositeAttributes<A,F,C,S> & Required<CompositeAttributes> & SK>
             : never
 }
 
@@ -464,7 +477,8 @@ export interface QueryOptions {
 }
 
 // subset of QueryOptions
-export interface ParseOptions {
+export interface ParseOptions<Attributes> {
+    attributes?: ReadonlyArray<Attributes>;
     ignoreOwnership?: boolean;
 }
 
@@ -510,6 +524,162 @@ export type OptionalDefaultEntityIdentifiers = {
     __edb_v__?: string;
 }
 
+interface GoBatchGetTerminalOptions<Attributes> {
+    raw?: boolean;
+    table?: string;
+    limit?: number;
+    params?: object;
+    includeKeys?: boolean;
+    originalErr?: boolean;
+    ignoreOwnership?: boolean;
+    pages?: number;
+    attributes?: ReadonlyArray<Attributes>;
+    unprocessed?: "raw" | "item";
+    concurrency?: number;
+    preserveBatchOrder?: boolean;
+    listeners?: Array<ElectroEventListener>;
+    logger?: ElectroEventListener;
+}
+
+interface GoQueryTerminalOptions<Attributes> {
+    raw?: boolean;
+    table?: string;
+    limit?: number;
+    params?: object;
+    includeKeys?: boolean;
+    originalErr?: boolean;
+    ignoreOwnership?: boolean;
+    pages?: number;
+    attributes?: ReadonlyArray<Attributes>;
+    listeners?: Array<ElectroEventListener>;
+    logger?: ElectroEventListener;
+}
+
+interface PageQueryTerminalOptions<Attributes> extends GoQueryTerminalOptions<Attributes> {
+    pager?: "raw" | "item" | "named";
+    raw?: boolean;
+    table?: string;
+    limit?: number;
+    includeKeys?: boolean;
+    originalErr?: boolean;
+    ignoreOwnership?: boolean;
+    attributes?: ReadonlyArray<Attributes>;
+    listeners?: Array<ElectroEventListener>;
+    logger?: ElectroEventListener;
+}
+
+export interface ParamTerminalOptions<Attributes> {
+    table?: string;
+    limit?: number;
+    params?: object;
+    originalErr?: boolean;
+    attributes?: ReadonlyArray<Attributes>;
+    response?: "default" | "none" | 'all_old' | 'updated_old' | 'all_new' | 'updated_new';
+}
+
+type GoBatchGetTerminal<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseItem> = <Options extends GoBatchGetTerminalOptions<keyof ResponseItem>>(options?: Options) =>
+    Options extends GoBatchGetTerminalOptions<infer Attr>
+        ? 'preserveBatchOrder' extends keyof Options
+            ? Options['preserveBatchOrder'] extends true
+                ? Promise<[
+                    Array<Resolve<{
+                        [
+                        Name in keyof ResponseItem as Name extends Attr
+                            ? Name
+                            : never
+                        ]: ResponseItem[Name]
+                    } | null>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>
+                ]>
+                : Promise<[
+                    Array<Resolve<{
+                        [
+                        Name in keyof ResponseItem as Name extends Attr
+                            ? Name
+                            : never
+                        ]: ResponseItem[Name]
+                    }>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>
+                ]>
+            : Promise<[
+                Array<Resolve<{
+                    [
+                    Name in keyof ResponseItem as Name extends Attr
+                        ? Name
+                        : never
+                    ]: ResponseItem[Name]
+                }>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>
+            ]>
+        : 'preserveBatchOrder' extends keyof Options
+            ? Options['preserveBatchOrder'] extends true
+                ? [Array<Resolve<ResponseItem | null>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>]
+                : [Array<Resolve<ResponseItem>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>]
+            : [Array<Resolve<ResponseItem>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>]
+
+type GoGetTerminal<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseItem> = <Options extends GoQueryTerminalOptions<keyof ResponseItem>>(options?: Options) =>
+    Options extends GoQueryTerminalOptions<infer Attr>
+        ? Promise<{
+            [
+            Name in keyof ResponseItem as Name extends Attr
+                ? Name
+                : never
+            ]: ResponseItem[Name]
+        } | null>
+        : Promise<ResponseItem | null>
+
+export type GoQueryTerminal<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, Item> = <Options extends GoQueryTerminalOptions<keyof Item>>(options?: Options) =>
+    Options extends GoQueryTerminalOptions<infer Attr>
+        ? Promise<Array<{
+            [
+            Name in keyof Item as Name extends Attr
+                ? Name
+                : never
+            ]: Item[Name]
+        }>>
+        : Promise<Array<Item>>
+
+export type EntityParseSingleItem<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseItem> =
+    <Options extends ParseOptions<keyof ResponseItem>>(item: ParseSingleInput, options?: Options) =>
+        Options extends ParseOptions<infer Attr>
+            ? {
+                [
+                Name in keyof ResponseItem as Name extends Attr
+                    ? Name
+                    : never
+                ]: ResponseItem[Name]
+            } | null
+            : ResponseItem | null
+
+export type EntityParseMultipleItems<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseItem> =
+    <Options extends ParseOptions<keyof ResponseItem>>(item: ParseMultiInput, options?: Options) =>
+        Options extends ParseOptions<infer Attr>
+            ? Array<{
+                [
+                Name in keyof ResponseItem as Name extends Attr
+                    ? Name
+                    : never
+                ]: ResponseItem[Name]
+            }>
+            : Array<ResponseItem>
+
+
+export type PageQueryTerminal<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, Item, CompositeAttributes> = <Options extends PageQueryTerminalOptions<keyof Item>>(page?: (CompositeAttributes & OptionalDefaultEntityIdentifiers) | null, options?: Options) =>
+    Options extends GoQueryTerminalOptions<infer Attr>
+        ? Promise<[
+            (CompositeAttributes & OptionalDefaultEntityIdentifiers) | null,
+            Array<{
+                [
+                Name in keyof Item as Name extends Attr
+                    ? Name
+                    : never
+                ]: Item[Name]
+            }>
+        ]>
+        : Promise<[
+            (CompositeAttributes & OptionalDefaultEntityIdentifiers) | null,
+            Array<ResponseType>
+        ]>;
+
+export type ParamTerminal<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, ResponseItem> = <P extends any = any, Options extends ParamTerminalOptions<keyof ResponseItem> = ParamTerminalOptions<keyof ResponseItem>>(options?: Options) => P;
+
 export type GoRecord<ResponseType, Options = QueryOptions> = <T = ResponseType>(options?: Options) => Promise<T>;
 
 export type BatchGoRecord<ResponseType, AlternateResponseType> = <O extends BulkOptions>(options?: O) =>
@@ -1037,18 +1207,6 @@ export type ItemAttribute<A extends Attribute> =
                                     : never
         : never
 
-type FormattedPutMapAttributes<A extends MapAttribute> = {
-    [P in keyof A["properties"]]: A["properties"][P] extends infer M
-        ? M extends HiddenAttribute
-            ? false
-            : M extends DefaultedAttribute
-                ? false
-                : M extends RequiredAttribute
-                    ? true
-                    : false
-        : false
-}
-
 export type ReturnedAttribute<A extends Attribute> =
     A["type"] extends infer R
         ? R extends "string" ? string
@@ -1079,27 +1237,6 @@ export type ReturnedAttribute<A extends Attribute> =
                                     : never
                                 : never
                         }
-                            // SkipKeys<{
-                            //     [P in keyof A["properties"]]: A["properties"][P] extends infer M
-                            //         ? M extends Attribute
-                            //           ? M extends HiddenAttribute
-                            //             ? SkipValue
-                            //             : M extends RequiredAttribute
-                            //                 ? ReturnedAttribute<M>
-                            //                 : SkipValue
-                            //             : never
-                            //           : never
-                            // }> & SkipKeys<{
-                            //   [P in keyof A["properties"]]?: A["properties"][P] extends infer M
-                            //         ? M extends Attribute
-                            //           ? M extends HiddenAttribute
-                            //             ? SkipValue
-                            //             : M extends RequiredAttribute
-                            //                 ? SkipValue
-                            //                 : ReturnedAttribute<M> | undefined
-                            //             : never
-                            //           : never
-                            // }>
                             : never
                         : R extends "list"
                             ? "items" extends keyof A
@@ -1151,27 +1288,6 @@ export type CreatedAttribute<A extends Attribute> =
                                     : never
                                 : never
                         }
-                            // ? SkipKeys<{
-                            //     [P in keyof A["properties"]]: A["properties"][P] extends infer M
-                            //         ? M extends Attribute
-                            //             ? M extends HiddenAttribute
-                            //               ? SkipValue
-                            //               : M extends DefaultedAttribute
-                            //                   ? SkipValue
-                            //                   : M extends RequiredAttribute
-                            //                       ? CreatedAttribute<M>
-                            //                       : SkipValue
-                            //             : never
-                            //     : never
-                            // }> & SkipKeys<{
-                            //   [P in keyof A["properties"]]?: A["properties"][P] extends infer M
-                            //     ? M extends Attribute
-                            //       ? M extends HiddenAttribute
-                            //         ? SkipValue
-                            //         : CreatedAttribute<M> | undefined
-                            //       : never
-                            //     : never
-                            // }>
                             : never
                         : R extends "list"
                             ? "items" extends keyof A
@@ -1632,9 +1748,8 @@ export class Entity<A extends string, F extends string, C extends string, S exte
     private config?: EntityConfiguration;
     constructor(schema: S, config?: EntityConfiguration);
 
-    get(key: AllTableIndexCompositeAttributes<A,F,C,S>): SingleRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S> | null>;
-    get(key: AllTableIndexCompositeAttributes<A,F,C,S>[]): BulkRecordOperationOptions<A,F,C,S, [Array<Resolve<ResponseItem<A,F,C,S>>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>], [Array<Resolve<ResponseItem<A,F,C,S>> | null>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>]>;
-
+    get(key: AllTableIndexCompositeAttributes<A,F,C,S>): SingleRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>;
+    get(key: AllTableIndexCompositeAttributes<A,F,C,S>[]): BatchGetRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>;
     delete(key: AllTableIndexCompositeAttributes<A,F,C,S>): DeleteRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>;
     delete(key: AllTableIndexCompositeAttributes<A,F,C,S>[]): BulkRecordOperationOptions<A,F,C,S, AllTableIndexCompositeAttributes<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S>[]>;
 
@@ -1671,8 +1786,26 @@ export class Entity<A extends string, F extends string, C extends string, S exte
     scan: RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], TableIndexCompositeAttributes<A,F,C,S>>;
     query: Queries<A,F,C,S>;
 
-    parse(item: ParseSingleInput, options?: ParseOptions): ResponseItem<A,F,C,S> | null;
-    parse(item: ParseMultiInput, options?: ParseOptions): ResponseItem<A,F,C,S>[];
+    parse<Options extends ParseOptions<keyof ResponseItem<A,F,C,S>>>(item: ParseSingleInput, options?: Options):
+        Options extends ParseOptions<infer Attr>
+        ? {
+                [
+                Name in keyof ResponseItem<A,F,C,S> as Name extends Attr
+                    ? Name
+                    : never
+            ]: ResponseItem<A,F,C,S>[Name]
+        } | null
+        : ResponseItem<A,F,C,S> | null
+    parse<Options extends ParseOptions<keyof ResponseItem<A,F,C,S>>>(item: ParseMultiInput, options?: Options):
+            Options extends ParseOptions<infer Attr>
+        ? Array<{
+            [
+                Name in keyof ResponseItem<A,F,C,S> as Name extends Attr
+                    ? Name
+                    : never
+            ]: ResponseItem<A,F,C,S>[Name]
+        }>
+        : Array<ResponseItem<A,F,C,S>>
     setIdentifier(type: "entity" | "version", value: string): void;
     client: any;
 }

package/package.json

@@ -1,17 +1,14 @@
 {
   "name": "electrodb",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {
-    "test": "mocha ./test/offline**.spec.js",
-    "test-ts": "mocha -r ts-node/register ./test/**.spec.ts",
-    "test-all": "mocha ./test/**.spec.js",
-    "test-all-local": "LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 node ./test/init.js && LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 mocha ./test/**.spec.js && LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 npm run test-ts && npm run test-types",
+    "test": "npm run test-types && LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 node ./test/init.js && LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 mocha -r ts-node/register ./test/**.spec.*",
     "test-types": "tsd",
-    "coverage": "nyc npm run test-all && nyc report --reporter=text-lcov | coveralls",
-    "coverage-coveralls-local": "nyc npm run test-all-local && nyc report --reporter=text-lcov | coveralls",
-    "coverage-html-local": "nyc npm run test-all-local && nyc report --reporter=html",
+    "coverage": "nyc npm test && nyc report --reporter=text-lcov | coveralls",
+    "coverage-coveralls-local": "nyc npm test && nyc report --reporter=text-lcov | coveralls",
+    "coverage-html-local": "nyc npm test && nyc report --reporter=html",
     "build:browser": "browserify playground/browser.js -o playground/bundle.js"
   },
   "repository": {
@@ -43,7 +40,7 @@
     "moment": "2.24.0",
     "nyc": "^15.1.0",
     "source-map-support": "^0.5.19",
-    "ts-node": "^10.8.1",
+    "ts-node": "^10.8.2",
     "tsd": "^0.21.0",
     "typescript": "^4.7.4",
     "uuid": "7.0.1"

package/src/clauses.js

@@ -1,4 +1,4 @@
-const { QueryTypes, MethodTypes, ItemOperations, ExpressionTypes, TableIndex } = require("./types");
+const { QueryTypes, MethodTypes, ItemOperations, ExpressionTypes, TableIndex, TerminalOperation } = require("./types");
 const {AttributeOperationProxy, UpdateOperations, FilterOperationNames} = require("./operations");
 const {UpdateExpression} = require("./update");
 const {FilterExpression} = require("./where");
@@ -579,6 +579,7 @@ let clauses = {
 				if (entity.client === undefined) {
 					throw new e.ElectroError(e.ErrorCodes.NoClientDefined, "No client defined on model");
 				}
+				options.terminalOperation = TerminalOperation.go;
 				let params = clauses.params.action(entity, state, options);
 				let {config} = entity._applyParameterOptions({}, state.getOptions(), options);
 				return entity.go(state.getMethod(), params, config);
@@ -595,11 +596,12 @@ let clauses = {
 				return Promise.reject(state.error);
 			}
 			try {
-				options.page = page;
-				options._isPagination = true;
 				if (entity.client === undefined) {
 					throw new e.ElectroError(e.ErrorCodes.NoClientDefined, "No client defined on model");
 				}
+				options.page = page;
+				options._isPagination = true;
+				options.terminalOperation = TerminalOperation.page;
 				let params = clauses.params.action(entity, state, options);
 				let {config} = entity._applyParameterOptions({}, state.getOptions(), options);
 				return entity.go(state.getMethod(), params, config);

package/src/entity.js

@@ -1,6 +1,6 @@
 "use strict";
 const { Schema } = require("./schema");
-const { KeyCasing, TableIndex, FormatToReturnValues, ReturnValues, EntityVersions, ItemOperations, UnprocessedTypes, Pager, ElectroInstance, KeyTypes, QueryTypes, MethodTypes, Comparisons, ExpressionTypes, ModelVersions, ElectroInstanceTypes, MaxBatchItems } = require("./types");
+const { KeyCasing, TableIndex, FormatToReturnValues, ReturnValues, EntityVersions, ItemOperations, UnprocessedTypes, Pager, ElectroInstance, KeyTypes, QueryTypes, MethodTypes, Comparisons, ExpressionTypes, ModelVersions, ElectroInstanceTypes, MaxBatchItems, TerminalOperation } = require("./types");
 const { FilterFactory } = require("./filters");
 const { FilterOperations } = require("./operations");
 const { WhereFactory } = require("./where");
@@ -84,13 +84,14 @@ class Entity {
 		return pkMatch;
 	}
 
-	ownsPager(pager, index) {
+	ownsPager(pager, index = TableIndex) {
 		if (pager === null) {
 			return false;
 		}
-		let tableIndex = TableIndex;
-		let tableIndexFacets = this.model.facets.byIndex[tableIndex];
-		let indexFacets = this.model.facets.byIndex[tableIndex];
+		let tableIndexFacets = this.model.facets.byIndex[TableIndex];
+		// todo: is the fact it doesn't use the provided index a bug?
+		// feels like collections may have played a roll into why this is this way
+		let indexFacets = this.model.facets.byIndex[TableIndex];
 
 		// Unknown index
 		if (tableIndexFacets === undefined || indexFacets === undefined) {
@@ -260,6 +261,7 @@ class Entity {
 	}
 
 	async _exec(method, params, config = {}) {
+		const entity = this;
 		const notifyQuery = () => {
 			this.eventManager.trigger({
 				type: "query",
@@ -285,6 +287,7 @@ class Entity {
 				return results;
 			})
 			.catch(err => {
+				notifyQuery();
 				notifyResults(err, false);
 				err.__isAWSError = true;
 				throw err;
@@ -822,6 +825,8 @@ class Entity {
 			pages: undefined,
 			listeners: [],
 			preserveBatchOrder: false,
+			attributes: [],
+			terminalOperation: undefined,
 		};
 
 		config = options.reduce((config, option) => {
@@ -834,6 +839,14 @@ class Entity {
 				config.params.ReturnValues = FormatToReturnValues[format];
 			}
 
+			if (option.terminalOperation in TerminalOperation) {
+				config.terminalOperation = TerminalOperation[option.terminalOperation];
+			}
+
+			if (Array.isArray(option.attributes)) {
+				config.attributes = config.attributes.concat(option.attributes);
+			}
+
 			if (option.preserveBatchOrder === true) {
 				config.preserveBatchOrder = true;
 			}
@@ -1019,7 +1032,103 @@ class Entity {
 				throw new Error(`Invalid method: ${method}`);
 		}
 		let applied = this._applyParameterOptions(params, options, config);
-		return this._applyParameterExpressionTypes(applied.parameters, filter);
+		return this._applyParameterExpressions(method, applied.parameters, applied.config, filter);
+	}
+
+	_applyParameterExpressions(method, parameters, config, filter) {
+		if (method !== MethodTypes.get) {
+			return this._applyParameterExpressionTypes(parameters, filter);
+		} else {
+			parameters = this._applyProjectionExpressions({parameters, config});
+			return this._applyParameterExpressionTypes(parameters, filter);
+		}
+
+	}
+
+	_applyProjectionExpressions({parameters = {}, config = {}} = {}) {
+		const attributes = config.attributes || [];
+		if (attributes.length === 0) {
+			return parameters;
+		}
+
+		const requiresRawResponse = !!config.raw;
+		const enforcesOwnership = !config.ignoreOwnership;
+		const requiresUserInvolvedPagination = TerminalOperation[config.terminalOperation] === TerminalOperation.page;
+		const isServerBound = TerminalOperation[config.terminalOperation] === TerminalOperation.go ||
+			TerminalOperation[config.terminalOperation] === TerminalOperation.page;
+
+		// 1. Take stock of invalid attributes, if there are any this should be considered
+		//    unintentional and should throw to prevent unintended results
+		// 2. Convert all attribute names to their respective "field" names
+		const unknownAttributes = [];
+		let attributeFields = new Set();
+		for (const attributeName of attributes) {
+			const fieldName = this.model.schema.getFieldName(attributeName);
+			if (typeof fieldName !== "string") {
+				unknownAttributes.push(attributeName);
+			} else {
+				attributeFields.add(fieldName);
+			}
+		}
+
+		// Stop doing work, prepare error message and throw
+		if (attributeFields.size === 0 || unknownAttributes.length > 0) {
+			let message = 'Unknown attributes provided in query options';
+			if (unknownAttributes.length) {
+				message += `: ${u.commaSeparatedString(unknownAttributes)}`;
+			}
+			throw new e.ElectroError(e.ErrorCodes.InvalidOptions, message);
+		}
+
+		// add ExpressionAttributeNames if it doesn't exist already
+		parameters.ExpressionAttributeNames = parameters.ExpressionAttributeNames || {};
+
+		if (
+			// The response you're returning:
+			// 1. is not expected to be raw
+			!requiresRawResponse
+			// 2. is making a request to the server
+			&& isServerBound
+			// 3. will expect entity identifiers down stream
+			&& enforcesOwnership
+
+		) {
+			// add entity identifiers to so items can be identified
+			attributeFields.add(this.identifiers.entity);
+			attributeFields.add(this.identifiers.version);
+
+			// if pagination is required you may enter into a scenario where
+			// the LastEvaluatedKey doesn't belong to entity and one must be formed.
+			// We must add the attributes necessary to make that key to not break
+			// pagination. This stinks.
+			if (
+				requiresUserInvolvedPagination
+				&& config.pager !== Pager.raw
+			) {
+				// LastEvaluatedKeys return the TableIndex keys and the keys for the SecondaryIndex
+				let tableIndexFacets = this.model.facets.byIndex[TableIndex];
+				let indexFacets = this.model.facets.byIndex[parameters.IndexName] || { all: [] };
+
+				for (const attribute of [...tableIndexFacets.all, ...indexFacets.all]) {
+					const fieldName = this.model.schema.getFieldName(attribute.name);
+					attributeFields.add(fieldName);
+				}
+			}
+		}
+
+		for (const attributeField of attributeFields) {
+			// prefix the ExpressionAttributeNames because some prefixes are not allowed
+			parameters.ExpressionAttributeNames['#' + attributeField] = attributeField;
+		}
+
+		// if there is already a ProjectionExpression (e.g. config "params"), merge it
+		if (typeof parameters.ProjectionExpression === 'string') {
+			parameters.ProjectionExpression = [parameters.ProjectionExpression, ...Object.keys([parameters.ExpressionAttributeNames])].join(', ');
+		} else {
+			parameters.ProjectionExpression = Object.keys(parameters.ExpressionAttributeNames).join(', ');
+		}
+
+		return parameters;
 	}
 
 	_batchGetParams(state, config = {}) {
@@ -1411,7 +1520,7 @@ class Entity {
 				throw new Error(`Invalid query type: ${state.query.type}`);
 		}
 		let applied = this._applyParameterOptions(parameters, state.query.options, options);
-		return applied.parameters;
+		return this._applyProjectionExpressions(applied);
 	}
 
 	_makeBetweenQueryParams(index, filter, pk, ...sk) {

package/src/schema.js

@@ -1,4 +1,4 @@
-const { CastTypes, ValueTypes, KeyCasing, AttributeTypes, AttributeMutationMethods, AttributeWildCard, PathTypes, TraverserIndexes } = require("./types");
+const { CastTypes, ValueTypes, KeyCasing, AttributeTypes, AttributeMutationMethods, AttributeWildCard, PathTypes } = require("./types");
 const AttributeTypeNames = Object.keys(AttributeTypes);
 const ValidFacetTypes = [AttributeTypes.string, AttributeTypes.number, AttributeTypes.boolean, AttributeTypes.enum];
 const e = require("./errors");
@@ -1263,7 +1263,7 @@ class Schema {
 	translateToFields(payload = {}) {
 		let record = {};
 		for (let [name, value] of Object.entries(payload)) {
-			let field = this.translationForTable[name];
+			let field = this.getFieldName(name);
 			if (value !== undefined) {
 				record[field] = value;
 			}
@@ -1271,6 +1271,12 @@ class Schema {
 		return record;
 	}
 
+	getFieldName(name) {
+		if (typeof name === 'string') {
+			return this.translationForTable[name];
+		}
+	}
+
 	checkCreate(payload = {}) {
 		let record = {};
 		for (let attribute of Object.values(this.attributes)) {
@@ -1320,13 +1326,18 @@ class Schema {
 	}
 
 	formatItemForRetrieval(item, config) {
+		let returnAttributes = new Set(config.attributes || []);
+		let hasUserSpecifiedReturnAttributes = returnAttributes.size > 0;
 		let remapped = this.translateFromFields(item, config);
 		let data = this._fulfillAttributeMutationMethod("get", remapped);
-		if (this.hiddenAttributes.size > 0) {
+		if (this.hiddenAttributes.size > 0 || hasUserSpecifiedReturnAttributes) {
 			for (let attribute of Object.keys(data)) {
 				if (this.hiddenAttributes.has(attribute)) {
 					delete data[attribute];
 				}
+				if (hasUserSpecifiedReturnAttributes && !returnAttributes.has(attribute)) {
+					delete data[attribute];
+				}
 			}
 		}
 		return data;

package/src/types.js

@@ -186,6 +186,11 @@ const EventSubscriptionTypes = [
 	"results"
 ];
 
+const TerminalOperation = {
+	go: 'go',
+	page: 'page',
+}
+
 module.exports = {
 	Pager,
 	KeyTypes,
@@ -210,6 +215,7 @@ module.exports = {
 	TraverserIndexes,
 	UnprocessedTypes,
 	AttributeWildCard,
+	TerminalOperation,
 	FormatToReturnValues,
 	AttributeProxySymbol,
 	ElectroInstanceTypes,

package/src/parse.js

@@ -1,45 +0,0 @@
-function getPartDetail(part = "") {
-  let detail = {
-      expression: "",
-      name: "",
-      value: "",
-  };
-  if (part.includes("[")) {
-      if (!part.match(/\[\d\]/gi)) {
-          throw new Error(`Invalid path part "${part}" has bracket containing non-numeric characters.`);
-      }
-      let [name] = part.match(/.*(?=\[)/gi);
-      detail.name = `#${name}`;
-      detail.value = name;
-  } else {
-      detail.name = `#${part}`;
-      detail.value = part;
-  }
-  detail.expression = `#${part}`;
-  return detail;
-}
-
-function parse(path = "") {
-  if (typeof path !== "string" || !path.length) {
-      throw new Error("Path must be a string with a non-zero length");
-  }
-  let parts = path.split(/\./gi);
-  let attr = getPartDetail(parts[0]).value;
-  let target = getPartDetail(parts[parts.length-1]);
-  if (target.expression.includes("[")) {
-
-  }
-  let names = {};
-  let expressions = [];
-  for (let part of parts) {
-      let detail = getPartDetail(part);
-      names[detail.name] = detail.value;
-      expressions.push(detail.expression);
-  }
-  return {attr, path, names, target: target.value, expression: expressions.join(".")};
-}
-
-module.exports = {
-  parse,
-  getPartDetail
-};