sportident.js 1.0.0

package/install.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+cat <<EOM >/etc/udev/rules.d/99-sportident.rules
+SUBSYSTEM=="usb", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="800a", MODE="0660", GROUP="plugdev", RUN="/bin/sh -c 'echo -n \$id:1.0 > /sys/bus/usb/drivers/cp210x/unbind'"
+EOM
+udevadm control --reload

package/jest.config.ts

@@ -0,0 +1,49 @@
+import type {Config} from 'jest';
+
+const totalCoverage = {
+    branches: 100,
+    functions: 100,
+    lines: 100,
+    statements: 100,
+};
+
+const percentCoverage = (percent: number) => ({
+    branches: percent,
+    functions: percent,
+    lines: percent,
+    statements: percent,
+})
+
+const jestConfig: Config = {
+    transform: {
+        '^.+\\.tsx?$': 'ts-jest',
+    },
+    testEnvironment: 'jsdom',
+    testRegex: '.*/.*\\.test\\.tsx?',
+    testPathIgnorePatterns: ['node_modules/', 'lib/', '__snapshots__/', 'testUtils/'],
+    collectCoverage: true,
+    collectCoverageFrom: [
+        './**/src/**/*',
+    ],
+    coveragePathIgnorePatterns: ['node_modules/', 'lib/', '__snapshots__/', 'testUtils/'],
+    maxConcurrency: 1,
+    coverageThreshold: {
+        global: percentCoverage(10),
+        './src/': {
+            branches: 92,
+            functions: 89,
+            lines: 89,
+            statements: 88,
+        },
+        './src/SiCard': percentCoverage(92),
+        './src/SiDevice': percentCoverage(44),
+        './src/fakes': percentCoverage(43),
+        './src/SiStation': percentCoverage(83),
+        './src/storage': totalCoverage,
+        './src/utils': totalCoverage,
+        './src/constants.ts': totalCoverage,
+        './src/siProtocol.ts': totalCoverage,
+        './src/testUtils.ts': totalCoverage,
+    },
+};
+export default jestConfig;

package/nx.json

@@ -0,0 +1,39 @@
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "nx/tasks-runners/default",
+      "options": {
+        "cacheableOperations": [
+          "build",
+          "eslint",
+          "tsc",
+          "webpack",
+          "typedoc"
+        ]
+      }
+    }
+  },
+  "namedInputs": {
+    "src": ["{projectRoot}/src/**/*"],
+    "babelconfig": ["{workspaceRoot}/babel.config.js"],
+    "eslintconfig": ["{workspaceRoot}/eslint.base.js", "{workspaceRoot}/.eslintignore"],
+    "tsconfig": ["{workspaceRoot}/tsconfig.base.json", "{workspaceRoot}/tsconfig.json"]
+  },
+  "targetDefaults": {
+    "build": {
+      "outputs": ["{projectRoot}/lib"]
+    },
+    "eslint": {
+      "inputs": ["src", "eslintconfig", "tsconfig"]
+    },
+    "tsc": {
+      "outputs": ["{projectRoot}/lib"]
+    },
+    "webpack": {
+      "outputs": ["{projectRoot}/build"]
+    },
+    "typedoc": {
+      "outputs": ["{projectRoot}/docs"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "sportident.js",
+  "version": "1.0.0",
+  "description": "JavaScript interface to SportIdent devices",
+  "scripts": {
+    "build": "tsc -b --verbose && lerna run build",
+    "build-docs": "sh build-docs.sh",
+    "dependency-check": "dependency-cruise --config=./.dependency-cruiser.js packages/*/src",
+    "lint": "eslint",
+    "test": "jest; echo \"\n\n  Coverage: file://${PWD}/coverage/lcov-report/index.html\n\n\"",
+    "test:ci": "jest --runInBand",
+    "tsc-build": "tsc -b --verbose",
+    "tsc-clean": "tsc -b --clean"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fadnincx/sportident.js.git"
+  },
+  "keywords": [
+    "sportident",
+    "javascript",
+    "js"
+  ],
+  "author": "Marcel Würsten",
+  "contributors": [
+    {
+      "name": "Simon Hatt"
+    },
+    {
+      "name": "Marcel Würsten"
+    }
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "immutable": "^4.0.0-rc.12",
+    "lodash": "^4.17.15"
+  },
+  "bugs": {
+    "url": "https://github.com/fadnincx/sportident.js/issues"
+  },
+  "homepage": "https://github.com/fadnincx/sportident.js#readme",
+  "devDependencies": {
+    "@types/lodash": "^4.17.13",
+		"@types/w3c-web-serial": "^1.0.7",
+		"@types/w3c-web-usb": "^1.0.10",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2"
+  }
+}

package/src/SiCard/BaseSiCard.test.ts

@@ -0,0 +1,187 @@
+import { beforeEach, describe, expect, test } from '@jest/globals';
+import { proto } from '../constants';
+import type * as siProtocol from '../siProtocol';
+import { BaseSiCard } from './BaseSiCard';
+
+beforeEach(() => {
+	BaseSiCard.resetNumberRangeRegistry();
+});
+
+describe('BaseSiCard', () => {
+	class FakeSiCard1 extends BaseSiCard {
+		static typeSpecificInstanceFromMessage(_message: siProtocol.SiMessage): FakeSiCard1 | undefined {
+			return undefined;
+		}
+
+		typeSpecificRead() {
+			return Promise.resolve();
+		}
+	}
+	class FakeSiCard2 extends BaseSiCard {
+		static typeSpecificInstanceFromMessage(_message: siProtocol.SiMessage): FakeSiCard2 | undefined {
+			return undefined;
+		}
+
+		typeSpecificRead() {
+			return Promise.resolve();
+		}
+	}
+
+	test('registerNumberRange', () => {
+		BaseSiCard.registerNumberRange(100, 1000, FakeSiCard1);
+		BaseSiCard.registerNumberRange(0, 100, FakeSiCard2);
+		BaseSiCard.registerNumberRange(1000, 2000, FakeSiCard2);
+		expect(BaseSiCard.getTypeByCardNumber(-1)).toEqual(undefined);
+		expect(BaseSiCard.getTypeByCardNumber(0)).toEqual(FakeSiCard2);
+		expect(BaseSiCard.getTypeByCardNumber(99)).toEqual(FakeSiCard2);
+		expect(BaseSiCard.getTypeByCardNumber(100)).toEqual(FakeSiCard1);
+		expect(BaseSiCard.getTypeByCardNumber(999)).toEqual(FakeSiCard1);
+		expect(BaseSiCard.getTypeByCardNumber(1000)).toEqual(FakeSiCard2);
+		expect(BaseSiCard.getTypeByCardNumber(1999)).toEqual(FakeSiCard2);
+		expect(BaseSiCard.getTypeByCardNumber(2000)).toEqual(undefined);
+	});
+	test('fromCardNumber', () => {
+		BaseSiCard.registerNumberRange(100, 1000, FakeSiCard1);
+		const siCard500 = BaseSiCard.fromCardNumber(500);
+		expect(siCard500 instanceof BaseSiCard).toBe(true);
+		expect(siCard500 instanceof FakeSiCard1).toBe(true);
+		const siCard5000 = BaseSiCard.fromCardNumber(5000);
+		expect(siCard5000).toBe(undefined);
+	});
+	describe('detectFromMessage', () => {
+		let triedToGetInstance = false;
+		class SiCard1 extends BaseSiCard {
+			static typeSpecificInstanceFromMessage(message: siProtocol.SiMessage) {
+				triedToGetInstance = true;
+				if (message.mode !== undefined) {
+					return undefined;
+				}
+				return new SiCard1(1);
+			}
+
+			typeSpecificRead() {
+				return Promise.resolve();
+			}
+		}
+
+		beforeEach(() => {
+			BaseSiCard.registerNumberRange(1000, 10000, SiCard1);
+			BaseSiCard.registerNumberRange(10000, 20000, FakeSiCard2);
+		});
+
+		test('detects card from valid message', () => {
+			expect(triedToGetInstance).toBe(false);
+			const siCard500 = BaseSiCard.detectFromMessage({
+				command: proto.cmd.SI5_DET,
+				parameters: []
+			});
+			expect(triedToGetInstance).toBe(true);
+			expect(siCard500 instanceof SiCard1).toBe(true);
+			expect(siCard500?.cardNumber).toBe(1);
+		});
+
+		test('does not detect from NAK message', () => {
+			const nakMessage = BaseSiCard.detectFromMessage({
+				mode: proto.NAK
+			});
+			expect(nakMessage).toBe(undefined);
+		});
+	});
+	test('read', async () => {
+		class SiCard1 extends BaseSiCard {
+			typeSpecificRead() {
+				this.raceResult.startTime = {time:1};
+				return Promise.resolve();
+			}
+		}
+		const siCard500 = new SiCard1(500);
+		try {
+			await siCard500.confirm();
+			expect({ canConfirm: true }).toEqual({ canConfirm: false });
+		} catch (err) {
+			// ignore
+		}
+		siCard500.mainStation = {
+			sendMessage: (_message: siProtocol.SiMessage, _numResponses?: number) => Promise.resolve([])
+		};
+		const result = await siCard500.read();
+		expect(result).toBe(siCard500);
+		expect(JSON.stringify(siCard500.raceResult.startTime)).toBe(JSON.stringify({time:1}));
+		await siCard500.confirm();
+	});
+	const emptySiCard = new FakeSiCard1(501);
+	const nonemptySiCard = new FakeSiCard1(502);
+	nonemptySiCard.raceResult = {
+		cardNumber: 502,
+		clearTime: {time:1},
+		checkTime: {time:2},
+		startTime: {time:1},
+		punches: [{ code: 31, time: {time:2} }],
+		finishTime: {time:1},
+		cardHolder: { firstName: 'John' }
+	};
+	test('Empty SiCard toDict', async () => {
+		expect(emptySiCard.toDict()).toEqual({
+			cardNumber: 501,
+			clearTime: undefined,
+			checkTime: undefined,
+			startTime: undefined,
+			finishTime: undefined,
+			punches: undefined,
+			cardHolder: undefined
+		});
+	});
+	test('Non-empty SiCard toDict', async () => {
+		expect(nonemptySiCard.toDict()).toEqual({
+			cardNumber: 502,
+			clearTime: {time:1},
+			checkTime: {time:2},
+			startTime: {time:1},
+			finishTime: {time:1},
+			punches: [{ code: 31, time: {time:2} }],
+			cardHolder: { firstName: 'John' }
+		});
+	});
+	test('Empty SiCard toString', async () => {
+		expect(emptySiCard.toString()).toEqual('FakeSiCard1\nCard Number: 501\nClear: ?\nCheck: ?\nStart: ?\nFinish: ?\n? Punches\nCard Holder:\n?\n');
+	});
+	test('Non-empty SiCard toString', async () => {
+		expect(nonemptySiCard.toString()).toEqual('FakeSiCard1\nCard Number: 502\nClear: 1\nCheck: 2\nStart: 1\nFinish: 1\n31: 2\nCard Holder:\nfirstName: John\n');
+	});
+	test('Empty SiCard getMonotonizedRaceResult', async () => {
+		expect(emptySiCard.getMonotonizedRaceResult()).toEqual({
+			cardNumber: 501,
+			clearTime: undefined,
+			checkTime: undefined,
+			startTime: undefined,
+			finishTime: undefined,
+			punches: undefined,
+			cardHolder: undefined
+		});
+	});
+	test('Non-empty SiCard getMonotonizedRaceResult', async () => {
+		expect(nonemptySiCard.getMonotonizedRaceResult()).toEqual({
+			cardNumber: 502,
+			clearTime: {time:1},
+			checkTime: {time:2},
+			startTime: {time:43201},
+			finishTime: {time:86401},
+			punches: [{ code: 31, time: {time:43202} }],
+			cardHolder: { firstName: 'John' }
+		});
+	});
+	test('Empty SiCard getNormalizedRaceResult', async () => {
+		expect(() => emptySiCard.getNormalizedRaceResult()).toThrow();
+	});
+	test('Non-empty SiCard getNormalizedRaceResult', async () => {
+		expect(nonemptySiCard.getNormalizedRaceResult()).toEqual({
+			cardNumber: 502,
+			clearTime: {time:-43200},
+			checkTime: {time:-43199},
+			startTime: {time:0},
+			finishTime: {time:43200},
+			punches: [{ code: 31, time: {time:1} }],
+			cardHolder: { firstName: 'John' }
+		});
+	});
+});

package/src/SiCard/BaseSiCard.ts

@@ -0,0 +1,101 @@
+import _ from 'lodash';
+import { proto } from '../constants';
+import * as utils from '../utils';
+import type * as siProtocol from '../siProtocol';
+import type * as storage from '../storage';
+import type { IRaceResultData } from './IRaceResultData';
+import { makeStartZeroTime, monotonizeRaceResult, prettyRaceResult } from './raceResultTools';
+
+export type SiCardType<T extends BaseSiCard> = {
+	new (cardNumber: number): T;
+	typeSpecificInstanceFromMessage: (message: siProtocol.SiMessage) => T | undefined;
+};
+const initialRegistry: utils.NumberRangeRegistry<SiCardType<BaseSiCard>> = new utils.NumberRangeRegistry();
+
+export interface ISiMainStation {
+	sendMessage: (message: siProtocol.SiMessage, numResponses?: number, timeoutInMiliseconds?: number) => Promise<number[][]>;
+}
+
+export abstract class BaseSiCard {
+	// abstract static maxNumPunches: number;
+	static NumberRange: typeof utils.NumberRange = utils.NumberRange;
+	static cardNumberRangeRegistry: utils.NumberRangeRegistry<SiCardType<BaseSiCard>> = initialRegistry;
+
+	static resetNumberRangeRegistry(): void {
+		this.cardNumberRangeRegistry = new utils.NumberRangeRegistry();
+	}
+
+	static registerNumberRange<T extends BaseSiCard>(firstCardNumberInRange: number, firstCardNumberAfterRange: number, siCardType: SiCardType<T>): void {
+		const cardNumberRange = new utils.NumberRange(firstCardNumberInRange, firstCardNumberAfterRange);
+		this.cardNumberRangeRegistry.register(cardNumberRange, siCardType);
+	}
+
+	static getTypeByCardNumber<T extends BaseSiCard>(cardNumber: number): SiCardType<T> | undefined {
+		return this.cardNumberRangeRegistry.getValueForNumber(cardNumber) as SiCardType<T> | undefined;
+	}
+
+	// abstract static getPunchOffset(index: number): number;
+
+	static fromCardNumber(cardNumber: number): BaseSiCard | undefined {
+		const cardType = this.getTypeByCardNumber(cardNumber);
+		if (!cardType) {
+			return undefined;
+		}
+		return new cardType(cardNumber);
+	}
+
+	static detectFromMessage(message: siProtocol.SiMessage): BaseSiCard | undefined {
+		const possibleCards = this.cardNumberRangeRegistry.values.map((cardType) => cardType.typeSpecificInstanceFromMessage(message)).filter((cardInstance) => cardInstance !== undefined);
+		return possibleCards.get(0);
+	}
+
+	// abstract static typeSpecificInstanceFromMessage<Fields extends IBaseSiCardStorageFields>(
+	//     _message: siProtocol.SiMessage,
+	// ): BaseSiCard<Fields>|undefined;
+
+	public mainStation?: ISiMainStation | undefined;
+	public raceResult: IRaceResultData & { cardNumber: number };
+	public storage: storage.ISiStorage<unknown> = {} as storage.ISiStorage<unknown>;
+
+	constructor(cardNumber: number) {
+		this.raceResult = { cardNumber: cardNumber };
+	}
+
+	get cardNumber(): number {
+		return this.raceResult.cardNumber;
+	}
+
+	read(): Promise<BaseSiCard> {
+		return this.typeSpecificRead().then(() => this);
+	}
+
+	getNormalizedRaceResult(): IRaceResultData {
+		return makeStartZeroTime(this.getMonotonizedRaceResult());
+	}
+
+	getMonotonizedRaceResult(): IRaceResultData {
+		return monotonizeRaceResult(this.raceResult);
+	}
+
+	abstract typeSpecificRead(): Promise<void>;
+
+	confirm(): Promise<number[][]> {
+		if (!this.mainStation) {
+			return Promise.reject(new Error('No main station'));
+		}
+		return this.mainStation.sendMessage(
+			{
+				mode: proto.ACK
+			},
+			0
+		);
+	}
+
+	toDict(): IRaceResultData {
+		return this.raceResult;
+	}
+
+	toString(): string {
+		return `${this.constructor.name}\n${prettyRaceResult(this.raceResult)}`;
+	}
+}

package/src/SiCard/IRaceResultData.ts

@@ -0,0 +1,16 @@
+import type * as siProtocol from '../siProtocol';
+
+export interface IRaceResultData {
+	cardNumber?: number;
+	cardHolder?: { [property: string]: unknown };
+	clearTime?: siProtocol.SiTimestamp;
+	checkTime?: siProtocol.SiTimestamp;
+	startTime?: siProtocol.SiTimestamp;
+	finishTime?: siProtocol.SiTimestamp;
+	punches?: IPunch[];
+}
+
+export interface IPunch {
+	code: number;
+	time: siProtocol.SiTimestamp;
+}

package/src/SiCard/ISiCard.ts

@@ -0,0 +1,23 @@
+import type * as storage from '../storage';
+import type * as siProtocol from '../siProtocol';
+import type { IPunch, IRaceResultData } from './IRaceResultData';
+
+export interface ISiCard {
+	cardNumber: number;
+	storage: storage.ISiStorage<IBaseSiCardStorageFields>;
+	read: () => Promise<ISiCard>;
+	confirm: () => Promise<unknown>;
+	toDict: () => IRaceResultData;
+	toString: () => string;
+}
+
+export interface IBaseSiCardStorageFields {
+	cardNumber: number;
+	clearTime?: siProtocol.SiTimestamp;
+	checkTime: siProtocol.SiTimestamp;
+	startTime: siProtocol.SiTimestamp;
+	finishTime: siProtocol.SiTimestamp;
+	punchCount: number;
+	punches: IPunch[];
+	cardHolder: { [key: string]: unknown };
+}

package/src/SiCard/ISiCardExamples.ts

@@ -0,0 +1,4 @@
+export interface SiCardSample {
+	cardData: { [attr: string]: unknown } & { cardNumber: number };
+	storageData: (number | undefined)[];
+}

package/src/SiCard/index.ts

@@ -0,0 +1,2 @@
+export { BaseSiCard } from './BaseSiCard';
+export * from './types';