add startFrom method for easier paging - fixes #53

readme.md

@@ -187,6 +187,47 @@ db.listTables().exec().then(tables => {
 If you passed in a `prefix` property in the connection object, only the tables with that prefix will
 be returned.
 
+### Paging
+
+You can implement paging by using the `startFrom()` method together with the `LastEvaluatedKey` property returned when using the `raw()` method.
+
+```js
+const result = Employee.find({Organisation: 'Amazon'}).where({Salary: {$gt: 3000}}).limit(1).raw().exec()
+    .then(result => {
+        /**
+		 * {
+		 *     "Items": [
+		 *         { UserId: '1', FirstName: 'Foo', Name: 'Bar' }
+		 *     ],
+		 *     "Count": 1,
+		 *     "ScannedCount": 1,
+		 *     "LastEvaluatedKey": {
+		 *         Organisation: 'Amazon',
+		 *         UserId: '1'
+		 *     }
+		 * }
+		 */
+
+		// Retrieve the next page
+		return Employee.find({Organisation: 'Amazon'}).where({Salary: {$gt: 3000}}).startFrom(result.LastEvaluatedKey).limit(1).raw().exec()
+	})
+	.then(result => {
+        /**
+		 * {
+		 *     "Items": [
+		 *         { UserId: '2', FirstName: 'Unicorn', Name: 'Rainbow' }
+		 *     ],
+		 *     "Count": 1,
+		 *     "ScannedCount": 1,
+		 *     "LastEvaluatedKey": {
+		 *         Organisation: 'Amazon',
+		 *         UserId: '2'
+		 *     }
+		 * }
+		 */
+	});
+```
+
 ### Create a table
 
 A table can be created by either calling `create()` on a table instance or by calling `createTable` on the database instance.

src/lib/methods/base-query.ts

@@ -86,6 +86,17 @@ export abstract class BaseQuery extends Method {
 		return this;
 	}
 
+	/**
+	 * Start querying from the provided key. Ideally for paging.
+	 *
+	 * @param lastEvaluatedKey 	The primary key of the first item that this operation will evaluate. Use the value that was returned for L`astEvaluatedKey` in the previous operation.
+	 */
+	startFrom(lastEvaluatedKey: any) {
+		this.params.ExclusiveStartKey = lastEvaluatedKey;
+
+		return this;
+	}
+
 	/**
 	 * Limit the number of items returned. If the limit is set to 1, the exec method
 	 * will return the first object instead of an array with one object.

src/lib/types/params.ts

@@ -12,6 +12,7 @@ export interface Params {
 	ExpressionAttributeValues?: Map<any>;
 	ProjectionExpression?: string;
 	ScanIndexForward?: boolean;
+	ExclusiveStartKey?: any;
 	Limit?: number;
 	ReturnValues?: 'ALL_NEW' | 'ALL_OLD';
 	Select?: 'COUNT';

src/test/methods/find.ts

@@ -90,6 +90,25 @@ test.serial('limit', async t => {
 	});
 });
 
+test.serial('exclusive start key', async t => {
+	await Table.find({id: '5'}).startFrom({id: '10', foo: 'bar'}).exec();
+
+	t.deepEqual(queryStub.lastCall.args[0], {
+		TableName: 'Table',
+		KeyConditionExpression: '#k_id=:v_id',
+		ExclusiveStartKey: {
+			id: '10',
+			foo: 'bar'
+		},
+		ExpressionAttributeNames: {
+			'#k_id': 'id'
+		},
+		ExpressionAttributeValues: {
+			':v_id': '5'
+		}
+	});
+});
+
 test.serial('sort ascending', async t => {
 	await (Table.find({id: '5'}) as any).sort(1).exec();
 
@@ -226,6 +245,18 @@ test.serial('find all where', async t => {
 	});
 });
 
+test.serial('scan::exclusive start key', async t => {
+	await Table.find().startFrom({id: '10', foo: 'bar'}).exec();
+
+	t.deepEqual(scanStub.lastCall.args[0], {
+		TableName: 'Table',
+		ExclusiveStartKey: {
+			id: '10',
+			foo: 'bar'
+		}
+	});
+});
+
 test.serial('scan::result', async t => {
 	t.deepEqual(await Table.find().exec(), ['foo', 'bar', 'baz']);
 });