@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/utils/src/services/documentStore/versioned/dynamodb.ts

@@ -0,0 +1,167 @@
+import { AttributeValue, DynamoDB, PutItemCommand, QueryCommand, ScanCommand } from '@aws-sdk/client-dynamodb';
+import { Config } from '..';
+import { once } from '../../..';
+import { ConfigProviderForConfig, resolveConfigValue } from '../../../config';
+import { ifDefined } from '../../../guards';
+import { decodeDynamoDocument, encodeDynamoAttribute, encodeDynamoDocument } from '../dynamoEncoding';
+import { VersionedDocumentAuthor, VersionedTDocument } from '.';
+
+interface Initializer<C> {
+  configSpace?: C;
+  dynamoClient?: DynamoDB;
+}
+
+// i'm not really excited about getAuthor being required, but ts is getting confused about the type when unspecified
+export const dynamoVersionedDocumentStore = <C extends string = 'dynamodb'>(initializer?: Initializer<C>) => {
+  const init = ifDefined(initializer, {} as NonNullable<typeof initializer>);
+  const dynamodb = once(() => init.dynamoClient ?? new DynamoDB({apiVersion: '2012-08-10'}));
+
+  return <T extends VersionedTDocument<T>>() => (configProvider: {[_key in C]: ConfigProviderForConfig<Config>}) => <K extends keyof T, A extends undefined | ((...a: any[]) => Promise<VersionedDocumentAuthor>)>(_: {}, hashKey: K, options?: {afterWrite?: (item: T) => void | Promise<void>; getAuthor?: A}) => {
+    const tableName = once(() => resolveConfigValue(configProvider[ifDefined(init.configSpace, 'dynamodb' as C)].tableName));
+
+    return {
+      loadAllDocumentsTheBadWay: async() => {
+        const loadAllResults = async(ExclusiveStartKey?: {[key: string]: AttributeValue}): Promise<T[]> => {
+          const cmd = new ScanCommand({TableName: await tableName(), ExclusiveStartKey});
+          const result = await dynamodb().send(cmd);
+          const resultItems = result.Items?.map(decodeDynamoDocument) as T[] || [];
+
+          if (result.LastEvaluatedKey) {
+            return [...resultItems, ...await loadAllResults(result.LastEvaluatedKey)];
+          }
+
+          return resultItems;
+        };
+
+        const allResults = await loadAllResults().then(results => results.reduce(
+          (result, document) => {
+            const current = result.get(document[hashKey]);
+            if (!current || current.timestamp < document.timestamp) {
+              return result.set(document[hashKey], document);
+            }
+            return result;
+          }
+        , new Map<T[K], T>()));
+
+        return Array.from(allResults.values());
+      },
+      getVersions: async(id: T[K], startVersion?: number) => {
+        const cmd = new QueryCommand({
+          TableName: await tableName(),
+          KeyConditionExpression: '#hk = :hkv',
+          ExpressionAttributeValues: {
+              ':hkv': encodeDynamoAttribute(id)
+          },
+          ExpressionAttributeNames: {
+            '#hk': hashKey.toString()
+          },
+          ...(startVersion
+            ? { ExclusiveStartKey: {
+              [hashKey]: encodeDynamoAttribute(id),
+              timestamp: {N: startVersion.toString()}
+            }}
+            : {}
+          ),
+          ScanIndexForward: false,
+        });
+
+        return dynamodb().send(cmd).then(result => {
+          const items = result.Items?.map(decodeDynamoDocument) as T[] | undefined;
+
+          if (!items || items.length === 0) {
+            return undefined;
+          }
+
+          return {
+            items,
+            nextPageToken: result.LastEvaluatedKey ? decodeDynamoDocument(result.LastEvaluatedKey).timestamp as number : undefined
+          };
+        });
+      },
+      getItem: async(id: T[K], timestamp?: number) => {
+        let keyConditionExpression = '#hk = :hkv';
+        const expressionAttributeNames: { [key: string]: string } = {
+          '#hk': hashKey.toString()
+        };
+        const expressionAttributeValues: { [key: string]: AttributeValue } = {
+          ':hkv': encodeDynamoAttribute(id)
+        };
+
+        if (timestamp) {
+          keyConditionExpression += ' and #ts = :tsv';
+          expressionAttributeNames['#ts'] = 'timestamp';
+          expressionAttributeValues[':tsv'] = encodeDynamoAttribute(timestamp);
+        }
+
+        const cmd = new QueryCommand({
+          TableName: await tableName(),
+          KeyConditionExpression: keyConditionExpression,
+          ExpressionAttributeNames: expressionAttributeNames,
+          ExpressionAttributeValues: expressionAttributeValues,
+          ScanIndexForward: false,
+          Limit: 1
+        });
+
+        return dynamodb().send(cmd).then(result => {
+          return result.Items?.map(decodeDynamoDocument)[0] as T | undefined;
+        });
+      },
+      /* prepares a new version of a document with the given data, then allows some additional
+       * changes to be input to a `save` function that actually saves it. useful for additional
+       * changes based on the new document version or author. the document version and author
+       * cannot be modified */
+      prepareItem: async(
+        item: Omit<T, 'timestamp' | 'author'>,
+        ...authorArgs: A extends Function ? Parameters<A> : [VersionedDocumentAuthor]
+      ) => {
+        // this getAuthor type is terrible
+        const author = options?.getAuthor ? await options.getAuthor(...authorArgs) : authorArgs[0];
+        const timestamp = new Date().getTime();
+
+        return {
+          document: {...item, timestamp, author} as T,
+          save: async (changes?: Partial<Omit<T, 'timestamp' | 'author'>>) => {
+            const document = {
+              ...item,
+              ...changes,
+              timestamp,
+              author
+            } as T;
+
+            const cmd = new PutItemCommand({
+              TableName: await tableName(),
+              Item: encodeDynamoDocument(document),
+            });
+
+            const updatedDoc = await dynamodb().send(cmd)
+              .then(() => document);
+            await options?.afterWrite?.(updatedDoc);
+            return updatedDoc;
+          }
+        };
+      },
+      /* saves a new version of a document with the given data */
+      putItem: async(
+        item: Omit<T, 'timestamp' | 'author'>,
+        ...authorArgs: A extends Function ? Parameters<A> : [VersionedDocumentAuthor]
+      ) => {
+        // this getAuthor type is terrible
+        const author = options?.getAuthor ? await options.getAuthor(...authorArgs) : authorArgs[0];
+        const document = {
+          ...item,
+          timestamp: new Date().getTime(),
+          author
+        } as T;
+        const cmd = new PutItemCommand({
+          TableName: await tableName(),
+          Item: encodeDynamoDocument(document),
+        });
+
+        const updatedDoc = await dynamodb().send(cmd)
+          .then(() => document);
+        await options?.afterWrite?.(updatedDoc);
+        return updatedDoc;
+      },
+    };
+  };
+};

package/packages/utils/src/services/documentStore/versioned/file-system.spec.ts

@@ -0,0 +1,262 @@
+import { TextEncoder } from 'util';
+import { hashValue } from '../../..';
+import { fileSystemVersionedDocumentStore } from './file-system';
+import { VersionedDocumentRequiredFields } from '.';
+
+type TTestDocument = {
+  coolId: string;
+  name: string;
+} & VersionedDocumentRequiredFields;
+
+describe('fileSystemVersionedDocumentStore', () => {
+  const config = {fileSystem: {tableName: 'db'}};
+  const middleware = {};
+  let readFileSpy: jest.SpyInstance;
+  let writeFileSpy: jest.SpyInstance;
+  let mkdirSpy: jest.SpyInstance;
+  let readdirSpy: jest.SpyInstance;
+  let files: string[] = [];
+  let data: string | undefined;
+  let error: Error | null = null;
+  let fs: Pick<typeof import('fs'), 'mkdir' | 'readdir' | 'readFile' | 'writeFile'>;
+
+  let consoleError: jest.SpyInstance;
+
+  beforeEach(() => {
+    error = null;
+    files = [];
+    data = undefined;
+
+    consoleError = jest.spyOn(console, 'error').mockImplementation(() => null);
+
+    mkdirSpy = jest.fn()
+      .mockImplementation((_path, _options, cb) => cb(null));
+
+    readdirSpy = jest.fn()
+      .mockImplementation((_file, cb) => cb(error, files));
+
+    readFileSpy = jest.fn()
+      .mockImplementation((_file, cb) => cb(error, Buffer.from(new TextEncoder().encode(data).buffer)));
+    writeFileSpy = jest.fn()
+      .mockImplementation((_file, _data, cb) => cb(error));
+
+    fs = {mkdir: mkdirSpy, readdir: readdirSpy, readFile: readFileSpy, writeFile: writeFileSpy} as any;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+    consoleError.mockRestore();
+  });
+
+  describe('loadAllDocumentsTheBadWay', () => {
+    it('returns all records', async() => {
+      files = [`file/path/to/db/${hashValue('my-document-id')}.json`];
+      const testDoc = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [testDoc]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+
+      expect(await store.loadAllDocumentsTheBadWay()).toEqual([testDoc]);
+    });
+
+    it('works with null data', async() => {
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect(await store.loadAllDocumentsTheBadWay()).toEqual([]);
+    });
+  });
+
+  describe('getItem', () => {
+    it('allows loading records from file', async() => {
+      const testDoc = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [testDoc]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+
+      expect(await store.getItem('my-document-id')).toEqual(testDoc);
+    });
+
+    it('gets most recent version', async() => {
+      const testDoc1 = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      const testDoc2 = {coolId: 'my-document-id', timestamp: 234, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [testDoc1, testDoc2]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+
+      expect(await store.getItem('my-document-id')).toEqual(testDoc2);
+    });
+
+    it('can get specific versions', async() => {
+      const testDoc1 = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      const testDoc2 = {coolId: 'my-document-id', timestamp: 234, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [testDoc1, testDoc2]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect(await store.getItem('my-document-id', 123)).toEqual(testDoc1);
+      expect(await store.getItem('my-document-id', 234)).toEqual(testDoc2);
+    });
+
+    it('returns undefined for non-existent ids', async() => {
+      readFileSpy.mockImplementation((_file, cb) => cb({code: 'ENOENT'}, null));
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect(await store.getItem('my-document-id', 345)).toBeUndefined();
+      expect(await store.getItem('my-document-id')).toBeUndefined();
+    });
+
+    it('returns undefined for non-existent versions', async() => {
+      const testDoc1 = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      const testDoc2 = {coolId: 'my-document-id', timestamp: 234, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [testDoc1, testDoc2]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect(await store.getItem('my-document-id', 345)).toBeUndefined();
+    });
+  });
+
+  describe('putItem', () => {
+    beforeAll(() => {
+      jest.useFakeTimers();
+      jest.setSystemTime(new Date(2020, 6, 28));
+    });
+
+    afterAll(() => {
+      jest.useRealTimers();
+    });
+
+    it('saves document', async() => {
+      readFileSpy.mockImplementationOnce((_file, cb) => cb({code: 'ENOENT'}, null));
+
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      await store.putItem(testDoc, {type: 'system', reason: 'testing'});
+      const testData = JSON.stringify({id: 'my-document-id', items: [{...testDoc, timestamp: 1595894400000, author: {type: 'system', reason: 'testing'}}]}, null, 2);
+      expect(writeFileSpy).toHaveBeenCalledWith(`file/path/to/db/${hashValue('my-document-id')}.json`, testData, expect.anything());
+    });
+
+    it('saves new version of document', async() => {
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [{...testDoc, timestamp: 123, author: {type: 'system', reason: 'testing'}}]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      await store.putItem(testDoc, {type: 'system', reason: 'testing'});
+      const testData = JSON.stringify({id: 'my-document-id', items: [
+        {...testDoc, timestamp: 123, author: {type: 'system', reason: 'testing'}},
+        {...testDoc, timestamp: 1595894400000, author: {type: 'system', reason: 'testing'}},
+      ]}, null, 2);
+      expect(writeFileSpy).toHaveBeenCalledWith(`file/path/to/db/${hashValue('my-document-id')}.json`, testData, expect.anything());
+    });
+
+    it('returns new document', async() => {
+      readFileSpy.mockImplementationOnce((_file, cb) => cb({code: 'ENOENT'}, null));
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      const result = await store.putItem(testDoc, {type: 'system', reason: 'testing'});
+      expect(result).toEqual({...testDoc, timestamp: expect.any(Number), author: {type: 'system', reason: 'testing'}});
+    });
+
+    it('adds timestamp to document', async() => {
+      readFileSpy.mockImplementationOnce((_file, cb) => cb({code: 'ENOENT'}, null));
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      const result = await store.putItem(testDoc, {type: 'system', reason: 'testing'});
+      expect(result).toEqual({...testDoc, timestamp: 1595894400000, author: {type: 'system', reason: 'testing'}});
+    });
+
+    it('uses author provider', async() => {
+      readFileSpy.mockImplementationOnce((_file, cb) => cb({code: 'ENOENT'}, null));
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const getAuthor = (name: string) => Promise.resolve({type: 'user' as const, name, uuid: 'a uuid'});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', {getAuthor});
+      const result = await store.putItem(testDoc, 'a name');
+      expect(result).toEqual({...testDoc, timestamp: expect.any(Number), author: {type: 'user', name: 'a name', uuid: 'a uuid'}});
+    });
+  });
+
+  describe('prepareItem', () => {
+    beforeAll(() => {
+      jest.useFakeTimers();
+      jest.setSystemTime(new Date(2020, 6, 28));
+    });
+
+    afterAll(() => {
+      jest.useRealTimers();
+    });
+
+    it('saves document', async() => {
+      readFileSpy.mockImplementationOnce((_file, cb) => cb({code: 'ENOENT'}, null));
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', {skipAssert: true});
+      const {save} = await store.prepareItem(testDoc, {type: 'system', reason: 'testing'});
+      await save();
+      const testData = JSON.stringify({id: 'my-document-id', items: [
+        {...testDoc, timestamp: 1595894400000, author: {type: 'system', reason: 'testing'}},
+      ]}, null, 2);
+      expect(writeFileSpy).toHaveBeenCalledWith(`file/path/to/db/${hashValue('my-document-id')}.json`, testData, expect.anything());
+    });
+
+    it('saves version', async() => {
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [{...testDoc, timestamp: 123, author: {type: 'system', reason: 'testing'}}]});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', {skipAssert: false});
+      const {save} = await store.prepareItem(testDoc, {type: 'system', reason: 'testing'});
+      await save();
+      const testData = JSON.stringify({id: 'my-document-id', items: [
+        {...testDoc, timestamp: 123, author: {type: 'system', reason: 'testing'}},
+        {...testDoc, timestamp: 1595894400000, author: {type: 'system', reason: 'testing'}},
+      ]}, null, 2);
+      expect(writeFileSpy).toHaveBeenCalledWith(`file/path/to/db/${hashValue('my-document-id')}.json`, testData, expect.anything());
+    });
+
+    it('returns new document', async() => {
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      const {document} = await store.prepareItem(testDoc, {type: 'system', reason: 'testing'});
+      expect(document).toEqual({...testDoc, timestamp: expect.any(Number), author: {type: 'system', reason: 'testing'}});
+    });
+
+    it('adds timestamp to document', async() => {
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      const {document} = await store.prepareItem(testDoc, {type: 'system', reason: 'testing'});
+      expect(document).toEqual({...testDoc, timestamp: 1595894400000, author: {type: 'system', reason: 'testing'}});
+    });
+
+    it('uses author provider', async() => {
+      const testDoc = {coolId: 'my-document-id', name: 'my-doc'};
+      const getAuthor = (name: string) => Promise.resolve({type: 'user' as const, name, uuid: 'a uuid'});
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', {getAuthor});
+      const {document} = await store.prepareItem(testDoc, 'a name');
+      expect(document).toEqual({...testDoc, timestamp: expect.any(Number), author: {type: 'user', name: 'a name', uuid: 'a uuid'}});
+    });
+  });
+
+  describe('getVersions', () => {
+    it('gets versions for document', async() => {
+      const testDoc1 = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      const testDoc2 = {coolId: 'my-document-id', timestamp: 234, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [ testDoc1, testDoc2 ]}, null, 2);
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect((await store.getVersions('my-document-id'))?.items).toEqual([testDoc2, testDoc1]);
+    });
+
+    it('gets next page token', async() => {
+      const testDoc1 = {coolId: 'my-document-id', timestamp: 1, name: 'my-doc'};
+      const testDoc2 = {coolId: 'my-document-id', timestamp: 2, name: 'my-doc'};
+      const testDoc3 = {coolId: 'my-document-id', timestamp: 3, name: 'my-doc'};
+      const testDoc4 = {coolId: 'my-document-id', timestamp: 4, name: 'my-doc'};
+      const testDoc5 = {coolId: 'my-document-id', timestamp: 5, name: 'my-doc'};
+      const testDoc6 = {coolId: 'my-document-id', timestamp: 6, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [ testDoc1, testDoc2, testDoc3, testDoc4, testDoc5, testDoc6 ]}, null, 2);
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect((await store.getVersions('my-document-id'))?.nextPageToken).toBe(2);
+    });
+
+    it('gets undefined when data loaded with error', async() => {
+      readFileSpy.mockImplementationOnce((_file, cb) => cb({code: 'ENOENT'}, null));
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect((await store.getVersions('my-document-id'))?.items).toBeUndefined();
+    });
+
+    it('gets version with indicated start point', async() => {
+      const testDoc1 = {coolId: 'my-document-id', timestamp: 123, name: 'my-doc'};
+      const testDoc2 = {coolId: 'my-document-id', timestamp: 234, name: 'my-doc'};
+      const testDoc3 = {coolId: 'my-document-id', timestamp: 345, name: 'my-doc'};
+      data = JSON.stringify({id: 'my-document-id', items: [ testDoc1, testDoc2, testDoc3 ]}, null, 2);
+      const store = fileSystemVersionedDocumentStore({fs, dataDir: 'file/path/to'})<TTestDocument>()(config)(middleware, 'coolId', undefined);
+      expect((await store.getVersions('my-document-id', 345))?.items).toEqual([testDoc2, testDoc1]);
+    });
+  });
+});

package/packages/utils/src/services/documentStore/versioned/file-system.ts

@@ -0,0 +1,90 @@
+import { Config } from '..';
+import { ConfigProviderForConfig } from '../../../config';
+import { assertNoUndefined } from '../fileSystemAssert';
+import { fileSystemUnversionedDocumentStore } from '../unversioned/file-system';
+import { VersionedDocumentAuthor, VersionedTDocument } from '.';
+
+const PAGE_LIMIT=5;
+
+interface Initializer<C> {
+  dataDir: string;
+  fs?: Pick<typeof import('fs'), 'mkdir' | 'readdir' | 'readFile' | 'writeFile'>;
+  configSpace?: C;
+}
+
+type FileFormat<T extends VersionedTDocument<T>, K extends keyof T> = {id: T[K]; items: T[]};
+
+export const fileSystemVersionedDocumentStore = <C extends string = 'fileSystem'>(initializer: Initializer<C>) => <T extends VersionedTDocument<T>>() => (configProvider: {[_key in C]: ConfigProviderForConfig<Config>}) => <K extends keyof T, A extends undefined | ((...a: any[]) => Promise<VersionedDocumentAuthor>)>(_: {}, hashKey: K, options?: {getAuthor?: A; skipAssert?: boolean}) => {
+
+  const skipAssert = options?.skipAssert ?? false;
+  
+  const unversionedDocuments = fileSystemUnversionedDocumentStore(initializer)<FileFormat<T, K>>()(configProvider)({}, 'id', {skipAssert});
+
+  return {
+    loadAllDocumentsTheBadWay: () => {
+      return unversionedDocuments.loadAllDocumentsTheBadWay().then(documents => documents.map(document => {
+        return document.items[document.items.length - 1];
+      }));
+    },
+    getVersions: async(id: T[K], startVersion?: number) => {
+      if (!skipAssert) assertNoUndefined(id, ['id']);
+      const item = await unversionedDocuments.getItem(id);
+      const versions = item?.items.reverse();
+
+      if (!versions) {
+        return undefined;
+      }
+
+      const startIndex = startVersion ? versions.findIndex(version => version.timestamp === startVersion) + 1 : 0;
+      const items = versions.slice(startIndex, startIndex + PAGE_LIMIT);
+      const hasMore = (startIndex + 5) < versions.length;
+
+      return {
+        items,
+        nextPageToken: hasMore ? items[items.length - 1].timestamp : undefined
+      };
+    },
+    getItem: async(id: T[K], timestamp?: number) => {
+      if (!skipAssert) assertNoUndefined(id, ['id']);
+      const item = await unversionedDocuments.getItem(id);
+      if (timestamp) { return item?.items.find(version => version.timestamp === timestamp); }
+      return item ? item.items[item.items.length - 1] : undefined;
+    },
+    prepareItem: async(
+      item: Omit<T, 'timestamp' | 'author'>,
+      ...authorArgs: A extends Function ? Parameters<A> : [VersionedDocumentAuthor]
+    ) => {
+      // this getAuthor type is terrible
+      const author = options?.getAuthor ? await options.getAuthor(...authorArgs) : authorArgs[0];
+      const timestamp = new Date().getTime();
+
+      return {
+        document: {...item, timestamp, author} as T,
+        save: async (changes?: Partial<Omit<T, 'timestamp' | 'author'>>) => {
+          const document = {...item, ...changes, timestamp, author} as T;
+          if (!skipAssert) assertNoUndefined(document);
+          const container: FileFormat<T, K> = await unversionedDocuments.getItem(document[hashKey]) ?? {id: document[hashKey], items: []};
+          const updated = {...container, items: [...container.items, document]};
+          await unversionedDocuments.putItem(updated);
+
+          return document;
+        }
+      };
+    },
+    putItem: async(
+      item: Omit<T, 'timestamp' | 'author'>,
+      ...authorArgs: A extends Function ? Parameters<A> : [VersionedDocumentAuthor]
+    ) => {
+      const author = options?.getAuthor ? await options.getAuthor(...authorArgs) : authorArgs[0];
+      const document = {...item, timestamp: new Date().getTime(), author} as T;
+      if (!skipAssert) assertNoUndefined(document);
+      const container: FileFormat<T, K> = await unversionedDocuments.getItem(document[hashKey]) ?? {id: document[hashKey], items: []};
+
+      const updated = {...container, items: [...container.items, document]};
+
+      await unversionedDocuments.putItem(updated);
+
+      return document;
+    },
+  };
+};

package/packages/utils/src/services/documentStore/versioned/index.ts

@@ -0,0 +1,25 @@
+/* istanbul ignore file */
+import { TDocument } from '..';
+import { dynamoVersionedDocumentStore } from './dynamodb';
+
+export type VersionedDocumentAuthor = {
+  type: 'user';
+  uuid: string;
+  name: string;
+  reason?: string;
+} | {
+  type: 'system';
+  reason: string;
+};
+
+export type VersionedDocumentRequiredFields = {
+  timestamp: number;
+  author: VersionedDocumentAuthor;
+};
+
+// it would be easier if the data store document could be like `{doc: T, change: {timestamp, ...author}}`
+// and have the gateway abstract the nesting for get/put and expose it only when getting version history
+// but dynamo doesn't allow setting indexes on nested values so the id/timestamp have to be at the top level
+export type VersionedTDocument<T> = TDocument<T> & VersionedDocumentRequiredFields;
+
+export type VersionedDocumentStoreCreator = typeof dynamoVersionedDocumentStore;

package/packages/utils/src/services/exercisesGateway/README.md

@@ -0,0 +1,5 @@
+# exercisesGateway
+
+Typing/formatting for interacting with OpenStax Exercises
+
+Query format (for and/or): 'tag:"andKey1:andValue1" tag:"orKey1:orValue1,orKey2:orValue2"'