feat(common): Adds the peek() method to PKProvider

Also finishes fixing unit tests for the Agent PK refactor and adds documentation re #104
regal · Jun 28, 2019 · 5c00d18 · 5c00d18
1 parent bba1ea0
commit 5c00d18
Show file tree

Hide file tree

Showing 12 changed files with 228 additions and 112 deletions.
diff --git a/src/agents/impl/agent-keys.ts b/src/agents/impl/agent-keys.ts
@@ -1,8 +1,19 @@
+/*
+ * Contains the `Agent` primary key system.
+ *
+ * Copyright (c) Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import { buildPKProvider } from "../../common";
 
+/** The set of reserved `Agent` primary keys. */
 export const AGENT_RESERVED_KEYS = {
+    /** Every `GameInstance` has this key. */
     GAME_INSTANCE: 100,
+    /** Before an `Agent` is activated, it has this key. */
     INACTIVE: 99
 };
 
-export let STATIC_AGENT_PK_PROVIDER = buildPKProvider(AGENT_RESERVED_KEYS);
+/** The `Agent` `PKProvider` for static agents. */
+export const STATIC_AGENT_PK_PROVIDER = buildPKProvider(AGENT_RESERVED_KEYS);
diff --git a/src/agents/impl/agent-utils.ts b/src/agents/impl/agent-utils.ts
@@ -1,12 +1,22 @@
+/*
+ * Contains various utilities for the Agents component.
+ *
+ * Copyright (c) Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import { PK } from "../../common";
 import { Agent } from "../agent";
 import { AGENT_RESERVED_KEYS, STATIC_AGENT_PK_PROVIDER } from "./agent-keys";
 
+/** Shorthand for the `AGENT_RESERVED_KEYS.INACTIVE` primary key. */
 export const getInactiveAgentPK = () =>
     STATIC_AGENT_PK_PROVIDER.reserved(AGENT_RESERVED_KEYS.INACTIVE);
 
-export const isAgentActive = (id: PK<Agent>) =>
-    !getInactiveAgentPK().equals(id);
-
+/** Shorthand for the `AGENT_RESERVED_KEYS.GAME_INSTANCE` primary key. */
 export const getGameInstancePK = () =>
     STATIC_AGENT_PK_PROVIDER.reserved(AGENT_RESERVED_KEYS.GAME_INSTANCE);
+
+/** Determines whether an `Agent` has been activated, given its primary key. */
+export const isAgentActive = (id: PK<Agent>) =>
+    !getInactiveAgentPK().equals(id);
diff --git a/src/agents/impl/instance-agents-impl.ts b/src/agents/impl/instance-agents-impl.ts
@@ -40,6 +40,7 @@ export const buildInstanceAgents = (
 
 /** Implementation of `InstanceAgentsInternal`. */
 class InstanceAgentsImpl implements InstanceAgentsInternal {
+    /** The internal `Agent` `PKProvider`. */
     private _pkProvider: PKProvider<Agent>;
 
     constructor(

diff --git a/src/common/impl/pk-provider-impl.ts b/src/common/impl/pk-provider-impl.ts
@@ -94,4 +94,8 @@ export class PKProviderImpl<PKClass> implements PKProvider<PKClass> {
 
         this.lastPK = sortedPKs[sortedPKs.length - 1];
     }
+
+    public peek(): PK<PKClass> {
+        return this.lastPK.plus(1);
+    }
 }
diff --git a/src/common/keys.ts b/src/common/keys.ts
@@ -39,6 +39,14 @@ export interface PK<T> {
      */
     value(): string;
 
+    /**
+     * Returns the placement of this key in the list of all keys.
+     * For example, an index of 2 means this was the second key generated.
+     *
+     * This includes reserved keys; if a set of reserved keys was used
+     * to generate this key's `PKProvider`, the entry with the lowest value
+     * will have an index of 0.
+     */
     index(): number;
 }
 
@@ -82,7 +90,17 @@ export interface PKProvider<T> {
      */
     reserved(key: number): PK<T>;
 
+    /**
+     * Resets the `PKProvider`'s internal `PK` generator back to its start value.
+     * Any reserved keys used to generate this `PKProvider` will remain.
+     */
     reset(): void;
+
+    /**
+     * Provides the `PK` that would be generated by `PKProvider.next()` without
+     * incrementing the internal key generator.
+     */
+    peek(): PK<T>;
 }
 
 /**

diff --git a/src/common/type-utils.ts b/src/common/type-utils.ts
@@ -1,3 +1,10 @@
+/*
+ * Custom TypeScript utilities.
+ *
+ * Copyright (c) Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 /**
  * Makes readonly properties in an object mutable and requried.
  * Only use this when you need it; it's like admin access.

diff --git a/test/unit/agents.test.ts b/test/unit/agents.test.ts
@@ -2636,18 +2636,20 @@ describe("Agents", function() {
     });
 
     describe("StaticAgentRegistry", function() {
-        // it("StaticAgentRegistry.getNextAvailableId increments by 1 for each static agent", function() {
-        //     expect(StaticAgentRegistry.getNextAvailableId()).to.equal(1);
+        it("STATIC_AGENT_PK_PROVIDER increments by 1 for each static agent added to the static registry", function() {
+            const [_pk0, pk1, pk2, pk3, _pk4, pk5] = pks(5);
 
-        //     const D = new Dummy("D1", 10);
-        //     expect(StaticAgentRegistry.getNextAvailableId()).to.equal(2);
+            expect(STATIC_AGENT_PK_PROVIDER.peek().equals(pk1)).to.be.true;
 
-        //     const P = new Parent(D);
-        //     expect(StaticAgentRegistry.getNextAvailableId()).to.equal(3);
+            const D = new Dummy("D1", 10);
+            expect(STATIC_AGENT_PK_PROVIDER.peek().equals(pk2)).to.be.true;
+
+            const P = new Parent(D);
+            expect(STATIC_AGENT_PK_PROVIDER.peek().equals(pk3)).to.be.true;
 
-        //     const P2 = new Parent(new Dummy("D2", 5));
-        //     expect(StaticAgentRegistry.getNextAvailableId()).to.equal(5);
-        // });
+            const P2 = new Parent(new Dummy("D2", 5));
+            expect(STATIC_AGENT_PK_PROVIDER.peek().equals(pk5)).to.be.true;
+        });
 
         it("StaticAgentRegistry.hasAgentProperty works properly", function() {
             const D = new Dummy("D1", 10);

diff --git a/test/unit/api-hooks.test.ts b/test/unit/api-hooks.test.ts
@@ -3,7 +3,7 @@ import "mocha";
 
 import { on, noop } from "../../src/events";
 import { metadataWithOptions, getDemoMetadata } from "../test-utils";
-import { PropertyOperation } from "../../src/agents";
+import { PropertyOperation, getGameInstancePK } from "../../src/agents";
 import { RegalError } from "../../src/error";
 import {
     Game,
@@ -59,7 +59,7 @@ describe("API Hooks", function() {
                     name: "INPUT",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "input",
                             init: undefined,
@@ -101,7 +101,7 @@ describe("API Hooks", function() {
                     name: "SET INPUT",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "input",
                             init: undefined,
@@ -157,7 +157,7 @@ describe("API Hooks", function() {
                     name: "DOUBLE INPUT",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.MODIFIED,
                             property: "input",
                             init: "Test Command",
@@ -171,7 +171,7 @@ describe("API Hooks", function() {
                     name: "SET INPUT",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "input",
                             init: undefined,
@@ -230,7 +230,7 @@ describe("API Hooks", function() {
                     name: "START",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "init",
                             init: undefined,
@@ -270,7 +270,7 @@ describe("API Hooks", function() {
                     name: "SET INIT",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "init",
                             init: undefined,
@@ -339,7 +339,7 @@ describe("API Hooks", function() {
                     name: "APPEND FOO",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.MODIFIED,
                             property: "foo",
                             init: "One",
@@ -353,7 +353,7 @@ describe("API Hooks", function() {
                     name: "SET FOO",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "foo",
                             init: undefined,
@@ -367,7 +367,7 @@ describe("API Hooks", function() {
                     name: "SET INIT",
                     changes: [
                         {
-                            agentId: 0,
+                            agentId: getGameInstancePK(),
                             op: PropertyOperation.ADDED,
                             property: "init",
                             init: undefined,