From 0c49a3a23404170499a6144af32f56dfffb1da8e Mon Sep 17 00:00:00 2001 From: Inga Date: Wed, 20 Nov 2024 02:23:14 +0000 Subject: [PATCH] detailed README --- README.md | 293 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 292 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2526607..81963f1 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,296 @@ Source: https://www.programmfabrik.de/en/assignment-frontend-backend-developer-j # Solution +## Features + +* Does not have any client-side dependencies, does not use any third-party libraries on the client. +* Works in modern browsers as a single-page application, in offline mode. +* Works in older browsers / browsers with JS disabled as a plain old multi-page application (requiring internet connection). +* Hopefully more accessible than a typical single-page application. +* Supports multiple games on the same page, playable at the same time. +* Supports different game rules (the provided main page has two games with different rule sets). +* Supports custom board size. +* The computer opponent is unbeatable. +* The user can choose for any player to become a computer opponent at any time. +* The user can even choose for both players to become computer opponents and let them finish the game. +* Browser back and forward buttons work as undo / redo buttons for user moves (and other user actions). +* Visuals are acceptable. + +## Usage + +* `npm ci` to install dependencies; +* `npm check-and-run` to run linting, typechecking, tests, build everything and serve it from `PORT` environment variable or from port 3000. + +(Yes, strictly speaking it's not just a static webpage with a bunch of client-side scripts. +It's better. See "User interface" section in "Design" for more details.) + +## Design + +### Project layout + +A monorepo would complicate things, so everything here is in a single package. + +* `src/backend` for code that's running on backend only; +* `src/frontend` for code (and static assets) that's running in browser only; +* `src/shared` for code that's running on both. + +No bundlers are used; all TS (and TSX) code is compiled to JS, preserving module imports; +and then files in `src/frontend` and `src/shared` are served at `/frontend` and `/shared` respectively. + +### User interface / handling interactions + +Of course the obvious choice would be to implement everything in React or another reactive framework, +but where is the fun in that? +I wanted to minimise the size of the resulting frontend application, +and the best way to reduce the number of dependencies on frontend is to not have any dependencies, +to write vanilla JS. + +I've been hearing a lot about Web Components lately, so I decided to try to use them. +But there are some major design choices to be made with Web Components too, +different people use them in different ways. + +I liked what I've read at https://adactio.com/journal/20618, +https://toot.cat/@zkat/113134268521905449 and https://toot.cat/@zkat/113034798494038446, +so I decided to use them to augment / enhance regular static HTML. +I'm not sure if I was successful in trying to follow this approach, but it works! + +So the key ideas are: +* Store game state in a query string parameter; + make every interactable element on the page a button submitting this state; +* On backend, when the page is requested, generate a complete HTML page for this game state; +* On frontend, when JS is enabled and Web Components are supported: + intercept button clicks and update the URL accordingly on the client side; +* On frontend, when JS is enabled and Web Components are supported: + subscribe to URL changes and update the DOM accordingly + (which in most cases (except for resizing the board) + only involves setting some class names and button values and inner texts). + +As a result: +* On the first visit, a complete fully working HTML page is served, and can be interacted with immediately. +* If JS is disabled, everything will still work! + You click on a button, it submits a form, server generates another updated fully working HTML. +* But if JS is enabled, magic happens, you don't even need the network connection anymore. + You click on a button, client-side script updates the URL, + another client-side script notices this and updates the gaming board. +* When you click on back/forward browser buttons with JS disabled, + server is going to serve fully working HTML every time for the relevant game state. +* When you click on back/forward browser buttons with JS enabled, + client-side script notices this just the same as if you clicked on a game button, + and updates the gaming board accordingly. + +Plus some additional glue to make the components independent from each other, +so that there can be many games on the same page at the same time, +all in varying states, without conflicting or competing with each other. + +And, since I had to generate HTML on the server, I needed a templating library for that. +While I'm not using React on frontend here, JSX is a really nice language with good IDE support, +so I decided to use it on backend, just as a template engine. + +Main components of interest: + +#### Progressive form + +The idea: no matter whether JS is enabled or disabled, no matter whether the browser supports Web Components or not, +submitting the form should result in page URL being updated with all the new parameters overriding the old ones +(while the old parameters not present in the form should stay intact). + +Additionally, if JS is enabled and Web Components are supported, this should happen entirely on the client, +without any network requests. + +In order to achieve this, the form must be submitted with method=POST +(so that the current query parameters are not all erased), +and then either the server will merge current query parameters with submitted data +and redirect the client to the page with the new query parameters, +or the client-side web component will do the merging. + +* Server part is implemented in [`src/backend/progressive-form.ts`](/src/backend/progressive-form.ts). +* Client part is implemented in [`src/frontend/components/progressive-form.ts`](/src/frontend/components/progressive-form.ts). +* Usage example is in [`src/backend/components/counter.tsx`](/src/backend/components/counter.tsx). + +#### Game board + +The idea: minimize the amount of DOM tree changes, and minimize the amount of duplicate code between frontend and backend. + +So we have the main game element, to which a bunch of classes are applied dynamically, +depending on the current state of the game. +And various blocks of text / buttons which are displayed or not depending on the classes applied to the main element, +according to CSS stylesheet. +This helps to avoid having to store any texts in client-side JS; everything is already present in the generated HTML. + +Additionally, the board itself is just a table with a button in every cell. +And these buttons get their values and texts set dynamically, +and get enabled (when it's a valid move) or disabled (when the cell is occupied, or when the game is over) automatically. + +* Server part is implemented in [`src/branch/main/src/backend/components/boardgame.tsx`](/src/branch/main/src/backend/components/boardgame.tsx). +* Client part is implemented as web component in [`src/frontend/components/board-game.ts`](/src/frontend/components/board-game.ts). +* Shared part is implemented in [`src/branch/main/src/shared/display.ts`](/src/branch/main/src/shared/display.ts). + +#### Computer opponent + +The idea: if the game is configured by user to use a computer player, and it's the move of a computer player, +then compute the board state _after_ the move of a computer player, +and redirect the user to this new board state (in client-server mode) +or replace the location with this new board state (in offline SPA mode), +without leaving a trace of the intermediate state (when it was computer player's turn) in the history, +so that the history back/forward button only work as undo/redo for user actions +(with subsequent computer actions coupled to user actions that caused them). + +* Server part is implemented in [`src/backend/main/boardgame-handler.ts`](/src/backend/main/boardgame-handler.ts) +* Client part is implemented in the same [`src/frontend/components/board-game.ts`](/src/frontend/components/board-game.ts) (see call to `replaceLocation`). +* Shared part is implemented in [`src/branch/main/src/shared/gameplay/boardgame.ts`](/src/branch/main/src/shared/gameplay/boardgame.ts). + +### Gameplay + +Mostly defined in [`src/shared/datatypes`](/src/shared/datatypes), [`src/shared/gameplay`](/src/shared/gameplay) and [`src/shared/game-variants`](/src/shared/game-variants). + +The main idea is that every possible state of the board belongs to one of the four categories: +player X won, player Y won, undecided (neither won but moves can still be made) +and draw (neither won and moves can no longer be made because the board is full). + +Different game rulesets differ in how they define the win. + +And knowing which states are final in which way, we can walk through all possible gameplays +(since thankfully the game graph is cycle-free, because on every move the number of free squares decreases until it reaches zero) +to determine the eventual game outcome assuming perfect play, and the moves left until this outcome. + +For example, if it's X move now, and by adding X to one of the free squares we can achieve the state "X won", +this means that for the current state, the eventual outcome is "X wins in 1 move". +If, no matter where we add X, we end up in a state with eventual outcome "O wins in 3 moves", +this means that for the current state, the eventual outcome is "O wins in 4 moves". +And so on. + +The possible outcomes are ordered by their desirability +(wins for the current player are the most preferable, then draws, then loses; +smaller number of moves to win is preferable to larger number of moves to win, +while for draws and loses the prolonged game is preferred), +and then the most desirable one is picked and saved. + +So for every board state that can be achieved in legal game, +we know what's the most desirable outcome for the current player, +achievable assuming that both players play perfectly in their own interests. +And having only this data, it is easy to get the optimal move: +just pick the one that will get you to the state +where the most desirable outcome for the opponent is the same, +just with one less move until the end. + +This means that we can compute desirable outcomes for all possible achievable board states once, +and then use this information to generate moves for the computer player. + +The problem is that computing these states is somewhat computationally expensive. +Easy to do for 3x3 board, but the number of possible achievable board states explodes exponentially with board size; +for example for 4x4 board there are a bit under ten million achievable board states, +according to https://math.stackexchange.com/a/613505. + +If I was doing this in low-level language such as Zig, and for one fixed board size, +I would probably manage to optimize the algorithm to run in a reasonable time and consume reasonable amounts of memory: +e.g. every 4x4 board state could easily be compressed to a 32-bit value, +which would also allow one to do some bit flipping to relatively quickly +determine which squares are still free and generate next boards; +determining winning boards would be as easy as applying 10 different bit masks... +all in all, it would probably take O(n*log(n)) ~= on the order of hundreds of millions of instructions +(i.e. fractions of a second), and under a hundred megabytes of RAM. + +But writing such a heavily optimized code in JS, while also supporting custom board sizes, +is very much outside of the scope I wanted to take, and I spent too much time on this project already. + +The current inefficient JS implementation takes on the order of minute to compute all solutions for 4x4 board, +while consuming gigabytes of RAM, so I decided to limit it to 12 cells (i.e. 4x3/3x4 boards) max. + +The solutions are computed where they are needed (i.e. on backend for no-JS MPA, on frontend for SPA), +and then cached. + +Originally my idea was to use WebWorkers to compute them on frontend, to avoid blocking the UI, +but since boards larger than 3x4 are not supported anyway, +and all solutions for 3x4 boards are computed in fractions of a second, +I decided that this complexity is not needed. + +If computer player is selected for boards larger than 12 squares, no computer moves will be made, +and humans will have to make moves both for O and for X. + +Implementation: [`src/shared/gameplay/solver.ts`](/src/shared/gameplay/solver.ts). + +### Tests + +In addition to strict TS configuration (`npm run typecheck`) +and strict typechecked eslint configuration (`npm run lint`), +most of the shared code files are covered by extensive tests, +defined in `.spec.ts` files next to the code files (and also `src/shared/integration-tests`), +written with node-tap and runnable with `npm test` (which also checks code coverage for tested files, +and by default returns an error if the coverage is not 100%). + +### Dependencies + +Listed in `package.json`, installed with `npm ci`, not vendored. + +#### Dev dependencies (build/compile-time) + +* `tap`, a test framework. +* `typescript`, because it's so much easier to write even small projects in TS than in JS + (fixed at 5.7-rc because + (1) for code to run in browser as-is without a bundler, I'm using ES modules; + (2) for ts-node (used by node-tap) to work properly, imports need to be with `.ts` extension; + (3) for frontend to work, imports need to be with compiled `.js` extension, + and rewriting import extensions was only implemented in TS 5.7: + https://devblogs.microsoft.com/typescript/announcing-typescript-5-7-rc/#path-rewriting-for-relative-paths + which is not yet stable). +* `@tsconfig/strictest`, to avoid +* `eslint`, for linting (fixed at 9.14 because 9.15 had breaking changes in it, + https://github.com/typescript-eslint/typescript-eslint/issues/10338). +* `prettier`, to ensure common code style. +* `typescript-eslint`, for type-aware and type-checked linting. +* `copyfiles`, to copy static assets to the `dist` directory so that they can be next to compiled JS for frontend. +* `rimraf`, to cleanup `dist` directory before building. + +#### Backend dependencies (runtime) + +* `express`, because I needed a minimal server framework to handle requests and serve static files. +* `body-parser`, to handle POST requests in express. +* `preact`, `preact-render-to-string`, to render intermediate JSX code to HTML + (because I'm using JSX as a template language on backend). + +#### Frontend dependencies (runtime) + +None. + +## Supported browser engines + +* Gecko (Firefox): works in v132, both with JS enabled (offline mode) and with JS disabled (plain old client-server mode). +* Blink (e.g. Chromium and Chromium-based browsers): not checked, should work in reasonably recent versions, + both with JS enabled (offline mode) and with JS disabled (plain old client-server mode). +* WebKit (e.g. qutebrowser and notably Safari): not checked; should **not** work in offline mode, + because WebKit does not fully implement decade-old standard which Gecko and Blink supported since 2018: + https://github.com/WebKit/standards-positions/issues/97. + Everything should still work in online mode, falling back on client-server communication. + +## Known issues and quirks + +* The game does not work offline fully on client (i.e. without falling back on client-server communication) + in WebKit-based browsers (such as qutebrowser or Safari), see above. +* Playing against the computer opponent is only supported for boards under 12 squares (i.e. 4x3 or 3x4 max). +* The computer player moves might be counterintuitive at times, + and it might be difficult for a human player to get to lose the game, + because the computer player always assumes that the other player plays perfectly. +* Boards larger than 12 squares are not supported with computer players + (regardless of computer players selected, all moves on large boards must be made by humans); + but the user does not get any explicit visible notification about this, + the only explicit indication that something is wrong is an error message in console. + +## Remaining tasks + +* Implement error handling and handling of incorrect / malformed game states (since they come from the client). +* Improve UI for large boards (disable autoplayers when board is too large, + hide "enable autoplayer" buttons, provide clear indication to the user instead). +* Target older ES versions on the frontend, + so that offline-only game can work in all browsers fully supporting Web Components + (i.e. Blink-based and Firefox not older than 2018); + right now ES2022 is targeted. +* Figure out better and more consistent naming and project structure. +* Implement end-to-end tests with puppeteer / chromedriver (and run them both with JS enabled and with JS disabled). +* Implement unit tests for remaining shared code. +* Implement integration tests for backend and frontend code, maybe? +* Rewrite solver so that it doesn't take a minute to compute all games on 4x4 board + (which only has under 10 millions states that can be encountered during legal play). + ## Time spent By major chunks of work in git history: @@ -42,6 +332,7 @@ By major chunks of work in git history: and to make the resulting page somewhat presentable * ~2 hours to implement another set of tic-tac-toe rules (with tests), support for changing board size (both on backend and in web components). +* ~2 hours to write this README completely. -...which makes it ~18 hours total. I definitely did not expect to spend that much; +...which makes it ~20 hours total. I definitely did not expect to spend that much; but also originally I didn't think that the scope will expand this much. \ No newline at end of file