Merge pull request #1 from madscience/types-and-pagination

Create Relay types and OffsetCursorPaginator

Author: sgarner

.eslintrc.js

@@ -50,6 +50,7 @@ module.exports = {
     'no-useless-constructor': 'off',
     '@typescript-eslint/no-useless-constructor': 'off',
     '@typescript-eslint/no-parameter-properties': 'off',
+    '@typescript-eslint/no-non-null-assertion': 'off',
     '@typescript-eslint/consistent-type-assertions': [
       'error',
       {

barrelsby.json

@@ -0,0 +1,7 @@
+{
+  "directory": "src/",
+  "location": "all",
+  "structure": "flat",
+  "singleQuotes": true,
+  "delete": true
+}

package-lock.json

@@ -28,6 +28,7 @@
   },
   "devDependencies": {
     "@types/graphql-relay": "^0.4.11",
+    "@types/jest": "^25.1.3",
     "@types/joi": "^14.3.4",
     "@types/node": "12.x",
     "@typescript-eslint/eslint-plugin": "=2.21.0",

package.json

@@ -0,0 +1,43 @@
+import * as querystring from 'querystring';
+import Joi from 'joi';
+
+export class Cursor {
+  constructor(public readonly parameters: querystring.ParsedUrlQueryInput) {}
+
+  public toString(): string {
+    return querystring.stringify(this.parameters, '&', '=');
+  }
+
+  public encode(): string {
+    return Buffer.from(this.toString()).toString('base64');
+  }
+
+  public static decode(encodedString: string): querystring.ParsedUrlQuery {
+    // opaque cursors are base64 encoded, decode it first
+    const decodedString = Buffer.from(encodedString, 'base64').toString();
+
+    // cursor string is URL encoded, parse it into a map of parameters
+    return querystring.parse(decodedString, '&', '=', {
+      maxKeys: 20,
+    });
+  }
+
+  public static create(encodedString: string, schema: Joi.ObjectSchema): Cursor {
+    // opaque cursors are base64 encoded, decode it first
+    const decodedString = Buffer.from(encodedString, 'base64').toString();
+
+    // cursor string is URL encoded, parse it into a map of parameters
+    const parameters = querystring.parse(decodedString, '&', '=', {
+      maxKeys: 20,
+    });
+
+    // validate the cursor parameters match the schema we expect, this also converts data types
+    const { error, value: validatedParameters } = Joi.validate(parameters, schema);
+
+    if (error != null) {
+      throw error;
+    }
+
+    return new Cursor(validatedParameters);
+  }
+}

src/cursor/Cursor.ts

@@ -0,0 +1,54 @@
+import { OffsetCursor, OffsetCursorPaginator } from './OffsetCursorPaginator';
+
+describe('OffsetCursorPaginator', () => {
+  test('PageInfo is correct for first page', () => {
+    const paginator = new OffsetCursorPaginator({
+      take: 20,
+      skip: 0,
+      totalEdges: 50,
+    });
+    const pageInfo = paginator.createPageInfo(20);
+
+    expect(pageInfo.totalEdges).toBe(50);
+    expect(pageInfo.hasPreviousPage).toBe(false);
+    expect(pageInfo.hasNextPage).toBe(true);
+    expect(pageInfo.startCursor).toBeDefined();
+    expect(OffsetCursor.create(pageInfo.startCursor!).parameters.offset).toStrictEqual(0);
+    expect(pageInfo.endCursor).toBeDefined();
+    expect(OffsetCursor.create(pageInfo.endCursor!).parameters.offset).toStrictEqual(19);
+  });
+
+  test('PageInfo is correct for second page', () => {
+    const paginator = new OffsetCursorPaginator({
+      take: 20,
+      skip: 20,
+      totalEdges: 50,
+    });
+    const pageInfo = paginator.createPageInfo(20);
+
+    expect(pageInfo.totalEdges).toBe(50);
+    expect(pageInfo.hasPreviousPage).toBe(true);
+    expect(pageInfo.hasNextPage).toBe(true);
+    expect(pageInfo.startCursor).toBeDefined();
+    expect(OffsetCursor.create(pageInfo.startCursor!).parameters.offset).toStrictEqual(20);
+    expect(pageInfo.endCursor).toBeDefined();
+    expect(OffsetCursor.create(pageInfo.endCursor!).parameters.offset).toStrictEqual(39);
+  });
+
+  test('PageInfo is correct for last page', () => {
+    const paginator = new OffsetCursorPaginator({
+      take: 20,
+      skip: 40,
+      totalEdges: 50,
+    });
+    const pageInfo = paginator.createPageInfo(10);
+
+    expect(pageInfo.totalEdges).toBe(50);
+    expect(pageInfo.hasPreviousPage).toBe(true);
+    expect(pageInfo.hasNextPage).toBe(false);
+    expect(pageInfo.startCursor).toBeDefined();
+    expect(OffsetCursor.create(pageInfo.startCursor!).parameters.offset).toStrictEqual(40);
+    expect(pageInfo.endCursor).toBeDefined();
+    expect(OffsetCursor.create(pageInfo.endCursor!).parameters.offset).toStrictEqual(49);
+  });
+});

src/cursor/OffsetCursorPaginator.spec.ts

@@ -0,0 +1,115 @@
+import Joi from 'joi';
+import { ConnectionArgs, PageInfo } from '../type';
+import { Cursor } from './Cursor';
+import { ConnectionArgsValidationError, CursorValidationError } from '../error';
+
+export class OffsetCursor extends Cursor {
+  public parameters: {
+    offset: number;
+  };
+
+  public static create(encodedString: string): OffsetCursor {
+    const parameters = Cursor.decode(encodedString);
+
+    // validate the cursor parameters match the schema we expect, this also converts data types
+    const { error, value: validatedParameters } = Joi.validate(
+      parameters,
+      Joi.object({
+        offset: Joi.number()
+          .integer()
+          .min(0)
+          .empty('')
+          .required(),
+      }).unknown(false),
+    );
+
+    if (error != null) {
+      const errorMessages =
+        error.details != null ? error.details.map(detail => `- ${detail.message}`).join('\n') : `- ${error.message}`;
+
+      throw new CursorValidationError(
+        `A provided cursor value is not valid. The following problems were found:\n\n${errorMessages}`,
+      );
+    }
+
+    return new OffsetCursor(validatedParameters);
+  }
+}
+
+export class OffsetCursorPaginator {
+  public take: number = 20;
+  public skip: number = 0;
+  public totalEdges: number = 0;
+
+  constructor({ take, skip, totalEdges }: Pick<OffsetCursorPaginator, 'take' | 'skip' | 'totalEdges'>) {
+    this.take = take;
+    this.skip = skip;
+    this.totalEdges = totalEdges;
+  }
+
+  public createPageInfo(edgesInPage: number): PageInfo {
+    return {
+      startCursor: edgesInPage > 0 ? this.createCursor(0).encode() : null,
+      endCursor: edgesInPage > 0 ? this.createCursor(edgesInPage - 1).encode() : null,
+      hasNextPage: this.skip + edgesInPage < this.totalEdges,
+      hasPreviousPage: this.skip > 0,
+      totalEdges: this.totalEdges,
+    };
+  }
+
+  public createCursor(index: number): OffsetCursor {
+    return new OffsetCursor({ offset: this.skip + index });
+  }
+
+  public static createFromConnectionArgs(
+    { first, last, before, after }: ConnectionArgs,
+    totalEdges: number,
+  ): OffsetCursorPaginator {
+    let take: number = 20;
+    let skip: number = 0;
+
+    if (first != null) {
+      if (first > 100 || first < 1) {
+        throw new ConnectionArgsValidationError('The "first" argument accepts a value between 1 and 100, inclusive.');
+      }
+
+      take = first;
+      skip = 0;
+    }
+
+    if (last != null) {
+      if (first != null) {
+        throw new ConnectionArgsValidationError(
+          'It is not permitted to specify both "first" and "last" arguments simultaneously.',
+        );
+      }
+
+      if (last > 100 || last < 1) {
+        throw new ConnectionArgsValidationError('The "last" argument accepts a value between 1 and 100, inclusive.');
+      }
+
+      take = last;
+      skip = totalEdges > last ? totalEdges - last : 0;
+    }
+
+    if (after != null) {
+      if (last != null) {
+        throw new ConnectionArgsValidationError(
+          'It is not permitted to specify both "last" and "after" arguments simultaneously.',
+        );
+      }
+
+      skip = OffsetCursor.create(after).parameters.offset + 1;
+    }
+
+    if (before != null) {
+      throw new ConnectionArgsValidationError('This connection does not support the "before" argument for pagination.');
+    }
+
+    return new OffsetCursorPaginator({
+      take,
+      skip,
+      totalEdges,
+    });
+  }
+}

src/cursor/OffsetCursorPaginator.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Automatically generated by barrelsby.
+ */
+
+export * from './Cursor';
+export * from './OffsetCursorPaginator.spec';
+export * from './OffsetCursorPaginator';

src/cursor/index.ts

@@ -0,0 +1 @@
+export class ConnectionArgsValidationError extends Error {}

src/error/ConnectionArgsValidationError.ts

@@ -0,0 +1 @@
+export class CursorValidationError extends Error {}