@civ-clone/base-city-happiness-status 0.0.0-stage → 0.1.0

package/.gitattributes

@@ -0,0 +1,2 @@
+**/*.js linguist-generated=true
+

package/.github/workflows/build-on-push.yml

@@ -0,0 +1,39 @@
+name: Build and test application on push to remote
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # No lock file, so this tests what a consumer resolves. The settings match
+      # web-renderer's pnpm-workspace.yaml: several @civ-clone packages depend on
+      # each other as `github:` URLs, this project's own releases are often only
+      # minutes old, and nothing here needs a dependency's build script.
+      - run: >-
+          pnpm install --no-frozen-lockfile
+          --config.block-exotic-subdeps=false
+          --config.minimum-release-age=0
+          --config.strict-dep-builds=false
+      - run: npm run --if-present prettier:check
+      # The tests load the committed `.js`, so compile to prove the source
+      # type-checks, and fail if the committed output is stale. `--force`
+      # because a fresh checkout's timestamps can make `tsc --build` treat the
+      # committed output as up to date and skip the compile entirely.
+      - run: npm run --if-present ts:compile -- --force
+      - run: npm run --if-present prettier:format
+      # Stale *or never committed* output fails: `git diff` alone misses a new
+      # module whose `.js` was never added, which the published package would
+      # then omit. Only the compiled extensions, so the lock file the install
+      # writes cannot fail it; `node_modules` is ignored, so it stays out.
+      - run: |
+          git status --short --untracked-files=all -- '*.js' '*.d.ts' '*.js.map'
+          test -z "$(git status --porcelain --untracked-files=all -- '*.js' '*.d.ts' '*.js.map')"
+      - run: npm run --if-present test

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "semi": true,
+  "singleQuote": true
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Dom Hastings
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# base-city-happiness-status
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keeps a city's status, such as being in disorder or celebrating, from one turn to the next and in the save. Each status
+is a `core-pending-effect` `PendingEffect` on the city, named by the ruleset's own handler id, so the save records it:
+
+- `lib/cityStatus`:
+  - `cityStatus(handler, city, pendingEffects?)`: the city's recorded status, or `null`. Read before this turn's
+    update, it's the status carried over from the last turn (a second turn of disorder, a celebration that goes on).
+  - `updateCityStatus(handler, city, active, recorded, pendingEffects?, onStart?)`: records a status that has started
+    (calling `onStart` first) and ends one that has stopped.
+  - `registerCityStatusHandler(handler, event, pendingEffects?, engine?)`: emits `event` with the city when its status
+    ends. Register it when the rules are created, so a status loaded from a save can still end.
+  - `forgetCityStatuses(city, handlers, pendingEffects?)`: drops statuses without ending them, for a city that's gone.
+
+A library: it registers no rules. See `civ1-city-happiness` for Civilization's civil disorder and "We Love the King
+Day".

package/lib/cityStatus.d.ts

@@ -0,0 +1,50 @@
+import { Engine } from '@civ-clone/core-engine/Engine';
+import {
+  PendingEffect,
+  PendingEffectRegistry,
+} from '@civ-clone/core-pending-effect';
+import City from '@civ-clone/core-city/City';
+/**
+ * A city's status (in disorder, celebrating and the like) is kept as a `PendingEffect` on the city, named by the
+ * ruleset's `handler`. Pending effects are saved, so a loaded game knows which cities already had a status, and a
+ * status recorded at the start of one turn is still there at the start of the next: that's how a ruleset tells a
+ * city's second turn of disorder, or of celebrating, from its first.
+ */
+export declare const cityStatus: (
+  handler: string,
+  city: City,
+  pendingEffects?: PendingEffectRegistry
+) => PendingEffect | null;
+/**
+ * Emits `event` with the city when its status `handler` ends. Register it whenever the rules are created, so a status
+ * loaded from a save can still end.
+ */
+export declare const registerCityStatusHandler: (
+  handler: string,
+  event: string,
+  pendingEffects?: PendingEffectRegistry,
+  engine?: Engine
+) => void;
+/**
+ * Records the city's status `handler` when it has started (`active` with nothing `recorded`), calling `onStart` first,
+ * and ends it when it has stopped (not `active` with one `recorded`), which emits the event its handler was registered
+ * with. `recorded` is the city's status as it was before this turn's check (`cityStatus`), so a ruleset can act on a
+ * status carried over from the last turn before it's updated.
+ */
+export declare const updateCityStatus: (
+  handler: string,
+  city: City,
+  active: boolean,
+  recorded: PendingEffect | null,
+  pendingEffects?: PendingEffectRegistry,
+  onStart?: () => void
+) => void;
+/**
+ * Drops the city's statuses named in `handlers` without ending them, so no event is emitted: for a city that's gone,
+ * which would otherwise stay in the save.
+ */
+export declare const forgetCityStatuses: (
+  city: City,
+  handlers: string[],
+  pendingEffects?: PendingEffectRegistry
+) => void;

package/lib/cityStatus.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forgetCityStatuses = exports.updateCityStatus = exports.registerCityStatusHandler = exports.cityStatus = void 0;
+const Engine_1 = require("@civ-clone/core-engine/Engine");
+const core_pending_effect_1 = require("@civ-clone/core-pending-effect");
+/**
+ * A city's status (in disorder, celebrating and the like) is kept as a `PendingEffect` on the city, named by the
+ * ruleset's `handler`. Pending effects are saved, so a loaded game knows which cities already had a status, and a
+ * status recorded at the start of one turn is still there at the start of the next: that's how a ruleset tells a
+ * city's second turn of disorder, or of celebrating, from its first.
+ */
+const cityStatus = (handler, city, pendingEffects = core_pending_effect_1.instance) => {
+    var _a;
+    return (_a = pendingEffects
+        .getByTarget(city)
+        .find((pendingEffect) => pendingEffect.handler() === handler)) !== null && _a !== void 0 ? _a : null;
+};
+exports.cityStatus = cityStatus;
+/**
+ * Emits `event` with the city when its status `handler` ends. Register it whenever the rules are created, so a status
+ * loaded from a save can still end.
+ */
+const registerCityStatusHandler = (handler, event, pendingEffects = core_pending_effect_1.instance, engine = Engine_1.instance) => pendingEffects.handler(handler, (pendingEffect) => engine.emit(event, pendingEffect.target()));
+exports.registerCityStatusHandler = registerCityStatusHandler;
+/**
+ * Records the city's status `handler` when it has started (`active` with nothing `recorded`), calling `onStart` first,
+ * and ends it when it has stopped (not `active` with one `recorded`), which emits the event its handler was registered
+ * with. `recorded` is the city's status as it was before this turn's check (`cityStatus`), so a ruleset can act on a
+ * status carried over from the last turn before it's updated.
+ */
+const updateCityStatus = (handler, city, active, recorded, pendingEffects = core_pending_effect_1.instance, onStart = () => { }) => {
+    if (active && recorded === null) {
+        onStart();
+        pendingEffects.register(new core_pending_effect_1.PendingEffect(handler, city));
+    }
+    if (!active && recorded !== null) {
+        pendingEffects.discharge(recorded);
+    }
+};
+exports.updateCityStatus = updateCityStatus;
+/**
+ * Drops the city's statuses named in `handlers` without ending them, so no event is emitted: for a city that's gone,
+ * which would otherwise stay in the save.
+ */
+const forgetCityStatuses = (city, handlers, pendingEffects = core_pending_effect_1.instance) => pendingEffects
+    .getByTarget(city)
+    .filter((pendingEffect) => handlers.includes(pendingEffect.handler()))
+    .forEach((pendingEffect) => pendingEffects.unregister(pendingEffect));
+exports.forgetCityStatuses = forgetCityStatuses;
+//# sourceMappingURL=cityStatus.js.map

package/lib/cityStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cityStatus.js","sourceRoot":"","sources":["cityStatus.ts"],"names":[],"mappings":";;;AAAA,0DAGuC;AACvC,wEAIwC;AAGxC;;;;;GAKG;AACI,MAAM,UAAU,GAAG,CACxB,OAAe,EACf,IAAU,EACV,iBAAwC,8BAA6B,EAC/C,EAAE;;IACxB,OAAA,MAAA,cAAc;SACX,WAAW,CAAC,IAAI,CAAC;SACjB,IAAI,CACH,CAAC,aAA4B,EAAW,EAAE,CACxC,aAAa,CAAC,OAAO,EAAE,KAAK,OAAO,CACtC,mCAAI,IAAI,CAAA;CAAA,CAAC;AAVD,QAAA,UAAU,cAUT;AAEd;;;GAGG;AACI,MAAM,yBAAyB,GAAG,CACvC,OAAe,EACf,KAAa,EACb,iBAAwC,8BAA6B,EACrE,SAAiB,iBAAc,EACzB,EAAE,CACR,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,aAA4B,EAAE,EAAE,CAC/D,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,EAAE,CAAC,CAC3C,CAAC;AARS,QAAA,yBAAyB,6BAQlC;AAEJ;;;;;GAKG;AACI,MAAM,gBAAgB,GAAG,CAC9B,OAAe,EACf,IAAU,EACV,MAAe,EACf,QAA8B,EAC9B,iBAAwC,8BAA6B,EACrE,UAAsB,GAAG,EAAE,GAAE,CAAC,EACxB,EAAE;IACR,IAAI,MAAM,IAAI,QAAQ,KAAK,IAAI,EAAE;QAC/B,OAAO,EAAE,CAAC;QAEV,cAAc,CAAC,QAAQ,CAAC,IAAI,mCAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;KAC3D;IAED,IAAI,CAAC,MAAM,IAAI,QAAQ,KAAK,IAAI,EAAE;QAChC,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;KACpC;AACH,CAAC,CAAC;AAjBW,QAAA,gBAAgB,oBAiB3B;AAEF;;;GAGG;AACI,MAAM,kBAAkB,GAAG,CAChC,IAAU,EACV,QAAkB,EAClB,iBAAwC,8BAA6B,EAC/D,EAAE,CACR,cAAc;KACX,WAAW,CAAC,IAAI,CAAC;KACjB,MAAM,CAAC,CAAC,aAA4B,EAAW,EAAE,CAChD,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC,CAC3C;KACA,OAAO,CAAC,CAAC,aAA4B,EAAQ,EAAE,CAC9C,cAAc,CAAC,UAAU,CAAC,aAAa,CAAC,CACzC,CAAC;AAZO,QAAA,kBAAkB,sBAYzB"}

package/lib/cityStatus.ts

@@ -0,0 +1,85 @@
+import {
+  Engine,
+  instance as engineInstance,
+} from '@civ-clone/core-engine/Engine';
+import {
+  PendingEffect,
+  PendingEffectRegistry,
+  instance as pendingEffectRegistryInstance,
+} from '@civ-clone/core-pending-effect';
+import City from '@civ-clone/core-city/City';
+
+/**
+ * A city's status (in disorder, celebrating and the like) is kept as a `PendingEffect` on the city, named by the
+ * ruleset's `handler`. Pending effects are saved, so a loaded game knows which cities already had a status, and a
+ * status recorded at the start of one turn is still there at the start of the next: that's how a ruleset tells a
+ * city's second turn of disorder, or of celebrating, from its first.
+ */
+export const cityStatus = (
+  handler: string,
+  city: City,
+  pendingEffects: PendingEffectRegistry = pendingEffectRegistryInstance
+): PendingEffect | null =>
+  pendingEffects
+    .getByTarget(city)
+    .find(
+      (pendingEffect: PendingEffect): boolean =>
+        pendingEffect.handler() === handler
+    ) ?? null;
+
+/**
+ * Emits `event` with the city when its status `handler` ends. Register it whenever the rules are created, so a status
+ * loaded from a save can still end.
+ */
+export const registerCityStatusHandler = (
+  handler: string,
+  event: string,
+  pendingEffects: PendingEffectRegistry = pendingEffectRegistryInstance,
+  engine: Engine = engineInstance
+): void =>
+  pendingEffects.handler(handler, (pendingEffect: PendingEffect) =>
+    engine.emit(event, pendingEffect.target())
+  );
+
+/**
+ * Records the city's status `handler` when it has started (`active` with nothing `recorded`), calling `onStart` first,
+ * and ends it when it has stopped (not `active` with one `recorded`), which emits the event its handler was registered
+ * with. `recorded` is the city's status as it was before this turn's check (`cityStatus`), so a ruleset can act on a
+ * status carried over from the last turn before it's updated.
+ */
+export const updateCityStatus = (
+  handler: string,
+  city: City,
+  active: boolean,
+  recorded: PendingEffect | null,
+  pendingEffects: PendingEffectRegistry = pendingEffectRegistryInstance,
+  onStart: () => void = () => {}
+): void => {
+  if (active && recorded === null) {
+    onStart();
+
+    pendingEffects.register(new PendingEffect(handler, city));
+  }
+
+  if (!active && recorded !== null) {
+    pendingEffects.discharge(recorded);
+  }
+};
+
+/**
+ * Drops the city's statuses named in `handlers` without ending them, so no event is emitted: for a city that's gone,
+ * which would otherwise stay in the save.
+ */
+export const forgetCityStatuses = (
+  city: City,
+  handlers: string[],
+  pendingEffects: PendingEffectRegistry = pendingEffectRegistryInstance
+): void =>
+  pendingEffects
+    .getByTarget(city)
+    .filter((pendingEffect: PendingEffect): boolean =>
+      handlers.includes(pendingEffect.handler())
+    )
+    .forEach((pendingEffect: PendingEffect): void =>
+      pendingEffects.unregister(pendingEffect)
+    );

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@civ-clone/base-city-happiness-status",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Keeps a city's status, such as disorder or celebrating, from one turn to the next and in the save.",
+  "repository": "git@github.com:civ-clone/base-city-happiness-status.git",
+  "keywords": [
+    "typescript",
+    "civilization"
+  ],
+  "author": "dom111 <dom111@users.noreply.github.com>",
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "npm run ts:compile && npm run prettier:format",
+    "prettier:check": "prettier --config .prettierrc --check '**/*.ts'",
+    "prettier:format": "prettier --config .prettierrc '**/*.ts' --write",
+    "test": "ts-mocha ./tests/*.test.ts",
+    "ts:compile": "tsc --build tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.0.0",
+    "@types/mocha": "^10.0.0",
+    "@types/node": "^16.0.0",
+    "chai": "^4.0.0",
+    "mocha": "^10.0.0",
+    "prettier": "^2.8.8",
+    "ts-mocha": "^10.0.0",
+    "typescript": "^4.0.0"
+  },
+  "dependencies": {
+    "@civ-clone/core-city": "^0.1.24",
+    "@civ-clone/core-engine": "^0.1.6",
+    "@civ-clone/core-pending-effect": "^0.1.2"
+  }
+}

package/tests/cityStatus.test.ts

@@ -0,0 +1,109 @@
+import {
+  PendingEffect,
+  PendingEffectRegistry,
+} from '@civ-clone/core-pending-effect';
+import {
+  cityStatus,
+  forgetCityStatuses,
+  registerCityStatusHandler,
+  updateCityStatus,
+} from '../lib/cityStatus';
+import City from '@civ-clone/core-city/City';
+import Engine from '@civ-clone/core-engine/Engine';
+import { expect } from 'chai';
+
+const UPSET = 'test:upset',
+  CHEERFUL = 'test:cheerful';
+
+describe('cityStatus', (): void => {
+  const setUp = () => {
+    const pendingEffects = new PendingEffectRegistry(),
+      events: [string, unknown][] = [],
+      engine = {
+        emit: (event: string, target: unknown) => events.push([event, target]),
+      } as unknown as Engine,
+      city = {} as City,
+      otherCity = {} as City;
+
+    registerCityStatusHandler(UPSET, 'city:calm', pendingEffects, engine);
+    registerCityStatusHandler(CHEERFUL, 'city:glum', pendingEffects, engine);
+
+    return { pendingEffects, events, city, otherCity };
+  };
+
+  it('has no status until one is recorded', (): void => {
+    const { pendingEffects, city } = setUp();
+
+    expect(cityStatus(UPSET, city, pendingEffects)).null;
+  });
+
+  it('records a status that has started, calling onStart first, and keeps it while it goes on', (): void => {
+    const { pendingEffects, events, city, otherCity } = setUp(),
+      started: number[] = [];
+
+    updateCityStatus(UPSET, city, true, null, pendingEffects, () =>
+      started.push(pendingEffects.entries().length)
+    );
+
+    const recorded = cityStatus(UPSET, city, pendingEffects);
+
+    expect(started).eql([0]);
+    expect(recorded?.handler()).equal(UPSET);
+    expect(recorded?.target()).equal(city);
+    expect(cityStatus(CHEERFUL, city, pendingEffects)).null;
+    expect(cityStatus(UPSET, otherCity, pendingEffects)).null;
+
+    // The next turn: still active, and the status recorded last turn is kept rather than recorded again.
+    updateCityStatus(UPSET, city, true, recorded, pendingEffects, () =>
+      started.push(-1)
+    );
+
+    expect(started).eql([0]);
+    expect(pendingEffects.getByTarget(city).length).equal(1);
+    expect(cityStatus(UPSET, city, pendingEffects)).equal(recorded);
+    expect(events).eql([]);
+  });
+
+  it('ends a status that has stopped, emitting its event', (): void => {
+    const { pendingEffects, events, city } = setUp();
+
+    updateCityStatus(UPSET, city, true, null, pendingEffects);
+    updateCityStatus(
+      UPSET,
+      city,
+      false,
+      cityStatus(UPSET, city, pendingEffects),
+      pendingEffects
+    );
+
+    expect(cityStatus(UPSET, city, pendingEffects)).null;
+    expect(events).eql([['city:calm', city]]);
+  });
+
+  it('does nothing for a status that is neither active nor recorded', (): void => {
+    const { pendingEffects, events, city } = setUp();
+
+    updateCityStatus(UPSET, city, false, null, pendingEffects);
+
+    expect(pendingEffects.entries()).eql([]);
+    expect(events).eql([]);
+  });
+
+  it('forgets only the named statuses of the city, without ending them', (): void => {
+    const { pendingEffects, events, city, otherCity } = setUp(),
+      unrelated = new PendingEffect('test:other', city);
+
+    pendingEffects.register(unrelated);
+    updateCityStatus(UPSET, city, true, null, pendingEffects);
+    updateCityStatus(CHEERFUL, city, true, null, pendingEffects);
+    updateCityStatus(UPSET, otherCity, true, null, pendingEffects);
+
+    forgetCityStatuses(city, [UPSET, CHEERFUL], pendingEffects);
+
+    expect(cityStatus(UPSET, city, pendingEffects)).null;
+    expect(cityStatus(CHEERFUL, city, pendingEffects)).null;
+    expect(cityStatus(UPSET, otherCity, pendingEffects)).not.null;
+    expect(pendingEffects.getByTarget(city)).eql([unrelated]);
+    expect(events).eql([]);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "lib": [
+      "es2020"
+    ],
+    "module": "commonjs",
+    "sourceMap": true,
+    "strict": true,
+    "target": "ES2018"
+  },
+  "exclude": [
+    "node_modules",
+    "tests"
+  ]
+}