@mnbroatch/boardgame.io 0.0.1

package/src/server/db/base.ts

@@ -0,0 +1,296 @@
+import type { Object } from 'ts-toolbelt';
+import type { State, Server, LogEntry } from '../../types';
+
+export enum Type {
+  SYNC = 0,
+  ASYNC = 1,
+}
+
+/**
+ * Type guard that checks if a storage implementation is synchronous.
+ */
+export function isSynchronous(storageAPI: Sync | Async): storageAPI is Sync {
+  return storageAPI.type() === Type.SYNC;
+}
+
+/**
+ * Indicates which fields the fetch operation should return.
+ */
+export interface FetchOpts {
+  state?: boolean;
+  log?: boolean;
+  metadata?: boolean;
+  initialState?: boolean;
+}
+
+/**
+ * Data that can be retrieved from a database fetch query
+ */
+export interface FetchFields {
+  state: State;
+  log: LogEntry[];
+  metadata: Server.MatchData;
+  initialState: State;
+}
+
+/**
+ * The result of the fetch operation.
+ */
+export type FetchResult<O extends FetchOpts> = Object.Pick<
+  FetchFields,
+  Object.SelectKeys<O, true>
+>;
+
+/**
+ * Options passed when listing matches.
+ */
+export interface ListMatchesOpts {
+  gameName?: string;
+  where?: {
+    isGameover?: boolean;
+    updatedBefore?: number;
+    updatedAfter?: number;
+  };
+}
+
+/**
+ * @deprecated Use ListMatchesOpts instead
+ */
+export interface ListGamesOpts {
+  gameName?: string;
+  where?: {
+    isGameover?: boolean;
+    updatedBefore?: number;
+    updatedAfter?: number;
+  };
+}
+
+/**
+ * Options passed when creating a new match.
+ */
+export interface CreateMatchOpts {
+  initialState: State;
+  metadata: Server.MatchData;
+}
+
+/**
+ * @deprecated Use CreateMatchOpts instead
+ */
+export interface CreateGameOpts {
+  initialState: State;
+  metadata: Server.MatchData;
+}
+
+export abstract class Async {
+  /* istanbul ignore next */
+  type() {
+    /* istanbul ignore next */
+    return Type.ASYNC;
+  }
+
+  /**
+   * Connect.
+   */
+  abstract connect();
+
+  /**
+   * Create a new match.
+   *
+   * This might just need to call setState and setMetadata in
+   * most implementations.
+   *
+   * However, it exists as a separate call so that the
+   * implementation can provision things differently when
+   * a match is created.  For example, it might stow away the
+   * initial match state in a separate field for easier retrieval.
+   */
+  /* istanbul ignore next */
+  async createMatch(matchID: string, opts: CreateMatchOpts): Promise<void> {
+    if (this.createGame) {
+      console.warn(
+        'The database connector does not implement a createMatch method.',
+        '\nUsing the deprecated createGame method instead.'
+      );
+      return this.createGame(matchID, opts);
+    } else {
+      console.error(
+        'The database connector does not implement a createMatch method.'
+      );
+    }
+  }
+
+  /**
+   * Create a new game.
+   *
+   * This might just need to call setState and setMetadata in
+   * most implementations.
+   *
+   * However, it exists as a separate call so that the
+   * implementation can provision things differently when
+   * a game is created.  For example, it might stow away the
+   * initial game state in a separate field for easier retrieval.
+   *
+   * @deprecated Use createMatch instead, if implemented
+   */
+  async createGame?(matchID: string, opts: CreateGameOpts): Promise<void>;
+
+  /**
+   * Update the game state.
+   *
+   * If passed a deltalog array, setState should append its contents to the
+   * existing log for this game.
+   */
+  abstract setState(
+    matchID: string,
+    state: State,
+    deltalog?: LogEntry[]
+  ): Promise<void>;
+
+  /**
+   * Update the game metadata.
+   */
+  abstract setMetadata(
+    matchID: string,
+    metadata: Server.MatchData
+  ): Promise<void>;
+
+  /**
+   * Fetch the game state.
+   */
+  abstract fetch<O extends FetchOpts>(
+    matchID: string,
+    opts: O
+  ): Promise<FetchResult<O>>;
+
+  /**
+   * Remove the game state.
+   */
+  abstract wipe(matchID: string): Promise<void>;
+
+  /**
+   * Return all matches.
+   */
+  /* istanbul ignore next */
+  async listMatches(opts?: ListMatchesOpts): Promise<string[]> {
+    if (this.listGames) {
+      console.warn(
+        'The database connector does not implement a listMatches method.',
+        '\nUsing the deprecated listGames method instead.'
+      );
+      return this.listGames(opts);
+    } else {
+      console.error(
+        'The database connector does not implement a listMatches method.'
+      );
+    }
+  }
+
+  /**
+   * Return all games.
+   *
+   * @deprecated Use listMatches instead, if implemented
+   */
+  async listGames?(opts?: ListGamesOpts): Promise<string[]>;
+}
+
+export abstract class Sync {
+  type() {
+    return Type.SYNC;
+  }
+
+  /**
+   * Connect.
+   */
+  connect() {
+    return;
+  }
+
+  /**
+   * Create a new match.
+   *
+   * This might just need to call setState and setMetadata in
+   * most implementations.
+   *
+   * However, it exists as a separate call so that the
+   * implementation can provision things differently when
+   * a match is created.  For example, it might stow away the
+   * initial match state in a separate field for easier retrieval.
+   */
+  /* istanbul ignore next */
+  createMatch(matchID: string, opts: CreateMatchOpts): void {
+    if (this.createGame) {
+      console.warn(
+        'The database connector does not implement a createMatch method.',
+        '\nUsing the deprecated createGame method instead.'
+      );
+      return this.createGame(matchID, opts);
+    } else {
+      console.error(
+        'The database connector does not implement a createMatch method.'
+      );
+    }
+  }
+
+  /**
+   * Create a new game.
+   *
+   * This might just need to call setState and setMetadata in
+   * most implementations.
+   *
+   * However, it exists as a separate call so that the
+   * implementation can provision things differently when
+   * a game is created.  For example, it might stow away the
+   * initial game state in a separate field for easier retrieval.
+   *
+   * @deprecated Use createMatch instead, if implemented
+   */
+  createGame?(matchID: string, opts: CreateGameOpts): void;
+
+  /**
+   * Update the match state.
+   *
+   * If passed a deltalog array, setState should append its contents to the
+   * existing log for this match.
+   */
+  abstract setState(matchID: string, state: State, deltalog?: LogEntry[]): void;
+
+  /**
+   * Update the match metadata.
+   */
+  abstract setMetadata(matchID: string, metadata: Server.MatchData): void;
+
+  /**
+   * Fetch the match state.
+   */
+  abstract fetch<O extends FetchOpts>(matchID: string, opts: O): FetchResult<O>;
+
+  /**
+   * Remove the match state.
+   */
+  abstract wipe(matchID: string): void;
+
+  /**
+   * Return all matches.
+   */
+  /* istanbul ignore next */
+  listMatches(opts?: ListMatchesOpts): string[] {
+    if (this.listGames) {
+      console.warn(
+        'The database connector does not implement a listMatches method.',
+        '\nUsing the deprecated listGames method instead.'
+      );
+      return this.listGames(opts);
+    } else {
+      console.error(
+        'The database connector does not implement a listMatches method.'
+      );
+    }
+  }
+
+  /**
+   * Return all games.
+   *
+   * @deprecated Use listMatches instead, if implemented
+   */
+  listGames?(opts?: ListGamesOpts): string[];
+}

package/src/server/db/flatfile.test.ts

@@ -0,0 +1,221 @@
+/*
+ * Copyright 2017 The boardgame.io Authors
+ *
+ * Use of this source code is governed by a MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+import { FlatFile } from './flatfile';
+import type { State, Server, LogEntry } from '../../types';
+
+describe('FlatFile', () => {
+  let db: FlatFile;
+
+  beforeAll(async () => {
+    db = new FlatFile({ dir: './tmp', logging: false });
+    await db.connect();
+  });
+
+  afterEach(async () => {
+    await db.clear();
+  });
+
+  test('basic', async () => {
+    // Must return undefined when no game exists.
+    const result = await db.fetch('matchID', { state: true });
+    expect(result.state).toEqual(undefined);
+
+    // Create game.
+    const state: unknown = { a: 1 };
+    const metadata: unknown = { metadata: true };
+
+    await db.createMatch('matchID', {
+      initialState: state as State,
+      metadata: metadata as Server.MatchData,
+    });
+
+    // Must return created game.
+    {
+      const result = await db.fetch('matchID', {
+        state: true,
+        metadata: true,
+        initialState: true,
+      });
+      expect(result.state).toEqual({ a: 1 });
+      expect(result.initialState).toEqual(result.state);
+      expect(result.metadata).toEqual({ metadata: true });
+    }
+
+    // Must return all keys
+    const keys = await db.listMatches();
+    expect(keys).toEqual(['matchID']);
+
+    // Must remove match from DB
+    await db.wipe('matchID');
+    expect(
+      await db.fetch('matchID', { metadata: true, state: true, log: true })
+    ).toEqual({});
+
+    // Shall not return error
+    await db.wipe('matchID');
+
+    // Shall create match, then clear DB, then check whether DB is cleared
+    await db.setState('game2', state as State);
+    await db.clear();
+    const keys2 = await db.listMatches();
+    expect(keys2).toHaveLength(0);
+  });
+
+  test('log', async () => {
+    const logEntry1: LogEntry = {
+      _stateID: 0,
+      action: {
+        type: 'MAKE_MOVE',
+        payload: { type: '', playerID: '0', args: [] },
+      },
+      turn: 0,
+      phase: '',
+    };
+
+    const logEntry2: LogEntry = {
+      _stateID: 1,
+      action: {
+        type: 'MAKE_MOVE',
+        payload: { type: '', playerID: '0', args: [] },
+      },
+      turn: 1,
+      phase: '',
+    };
+
+    await db.setState('matchID', null, [logEntry1]);
+    await db.setState('matchID', null, [logEntry2]);
+
+    const result = await db.fetch('matchID', { log: true });
+    expect(result.log).toEqual([logEntry1, logEntry2]);
+  });
+
+  describe('listMatches', () => {
+    beforeEach(async () => {
+      const state: unknown = { a: 1 };
+
+      await db.createMatch('matchID', {
+        initialState: state as State,
+        metadata: {
+          gameName: 'game1',
+          updatedAt: new Date(2020, 3).getTime(),
+        } as Server.MatchData,
+      });
+
+      await db.createMatch('matchID2', {
+        initialState: state as State,
+        metadata: {
+          gameName: 'game1',
+          gameover: 'gameover',
+          updatedAt: new Date(2020, 5).getTime(),
+        } as Server.MatchData,
+      });
+
+      await db.createMatch('matchID3', {
+        initialState: state as State,
+        metadata: {
+          gameName: 'game2',
+          updatedAt: new Date(2020, 4).getTime(),
+        } as Server.MatchData,
+      });
+    });
+
+    test('filter by gameName', async () => {
+      let keys = await db.listMatches();
+      expect(keys).toEqual(
+        expect.arrayContaining(['matchID', 'matchID2', 'matchID3'])
+      );
+
+      keys = await db.listMatches({ gameName: 'game1' });
+      expect(keys).toEqual(expect.arrayContaining(['matchID', 'matchID2']));
+
+      keys = await db.listMatches({ gameName: 'game2' });
+      expect(keys).toEqual(['matchID3']);
+    });
+
+    test('filter by isGameover', async () => {
+      let keys = await db.listMatches({});
+
+      expect(keys).toEqual(
+        expect.arrayContaining(['matchID', 'matchID2', 'matchID3'])
+      );
+
+      keys = await db.listMatches({ where: { isGameover: true } });
+      expect(keys).toEqual(['matchID2']);
+
+      keys = await db.listMatches({ where: { isGameover: false } });
+      expect(keys).toEqual(expect.arrayContaining(['matchID', 'matchID3']));
+    });
+
+    test('filter by updatedBefore', async () => {
+      const timestamp = new Date(2020, 4);
+
+      let keys = await db.listMatches({});
+      expect(keys).toEqual(
+        expect.arrayContaining(['matchID', 'matchID2', 'matchID3'])
+      );
+
+      keys = await db.listMatches({
+        where: { updatedBefore: timestamp.getTime() },
+      });
+      expect(keys).toEqual(expect.arrayContaining(['matchID']));
+    });
+
+    test('filter by updatedAfter', async () => {
+      const timestamp = new Date(2020, 4);
+
+      let keys = await db.listMatches({});
+      expect(keys).toEqual(
+        expect.arrayContaining(['matchID', 'matchID2', 'matchID3'])
+      );
+
+      keys = await db.listMatches({
+        where: { updatedAfter: timestamp.getTime() },
+      });
+      expect(keys).toEqual(['matchID2']);
+    });
+
+    test('filter combined', async () => {
+      const timestamp = new Date(2020, 4);
+      const timestamp2 = new Date(2020, 2, 15);
+      let keys = await db.listMatches({
+        gameName: 'chess',
+        where: { isGameover: true },
+      });
+      expect(keys).toEqual([]);
+
+      keys = await db.listMatches({
+        where: { isGameover: true, updatedBefore: timestamp.getTime() },
+      });
+      expect(keys).toEqual([]);
+
+      keys = await db.listMatches({
+        where: { isGameover: false, updatedBefore: timestamp.getTime() },
+      });
+      expect(keys).toEqual(['matchID']);
+
+      keys = await db.listMatches({
+        where: { isGameover: true, updatedAfter: timestamp.getTime() },
+      });
+      expect(keys).toEqual(['matchID2']);
+
+      keys = await db.listMatches({
+        where: { isGameover: false, updatedAfter: timestamp.getTime() },
+      });
+      expect(keys).toEqual([]);
+
+      keys = await db.listMatches({
+        where: {
+          updatedBefore: timestamp.getTime(),
+          updatedAfter: timestamp2.getTime(),
+        },
+      });
+      expect(keys).toEqual(['matchID']);
+    });
+  });
+});