DEVELOPMENT.md

Flatland Benchmarks Developer's Guide

Note

Documentation for platform developers.

Recommended tools and setup

It is recommended to use VSCode with the ESLint and Prettier extensions installed.

Node.js must be installed. It runs frontend and backend code as well as local scripts (e.g. npx lint-staged which will lint and format staged source files). Node.js includes npm, which is required to install node modules.

To complete your local setup, run

npm ci

in the project root folder. This will install all required node modules as listed in package-lock.json.

The project is configured to lint and format your source code before committing and also on explicit save (when using VSCode as described above). However, if you're not using VSCode or for some reason not using the extensions, your code will still be linted and formatted before a commit. Be aware that in this case lint warnings and errors will abort your commit!

If lint-staged fails and discards your changes, you can often git stash pop them back into existence. Run the lint npm script manually beforehand or install the VSCode plugins as described above to limit any surprises.

Developer notes

dev.001 - GET list returns previews instead of full resources

API endpoints listing resources - such as GET /benchmarks - should only return list of preview (URI + selected fields). The full resources themselves are then fetched in consecutive requests. This enables effective caching on the client side and minimizes transmitted data load.

2025-01-24, Olivier Stuker

dev.002 - GET resource returns array

API endpoints returning resources - such as GET /benchmarks/1 - should always return an array of resources. That way, the response body type is always the same, no matter whether a single or multiple resources were queried at once.

2025-01-24, Olivier Stuker

dev.003 - Use id=ANY() in WHERE clause

I did some tests (using explain analyze). Postgres optimizes id=ANY conditions in such a way that it will do an index scan if there's only one element in the array. Meaning id=ANY(1) has the same performance as id=1. With multiple elements, it will do a sequence scan, aborting at LIMIT.

2025-01-27, Olivier Stuker

dev.004 - GENERATED BY DEFAULT AS IDENTITY instead of SERIAL

https://www.reddit.com/r/PostgreSQL/comments/1ffqsvw/stop_using_serial_in_postgres/ recommends using GENERATED BY DEFAULT AS IDENTITY instead of SERIAL for auto-increment columns.

2025-01-27, Olivier Stuker

dev.005 - GET endpoints' id and ids are interchangeable

GET endpoints should always treat the id paramater as comma-separated list of values in accordance with dev.003.

2025-01-29, Olivier Stuker

Releases

• Release prs are automatically opened by release-please/release-please-action based on Conventional Commit Messages
• How do I change the version number?