From 31f97fd39202e5dbf596b9d8dcca6c925bda45dc Mon Sep 17 00:00:00 2001 From: Marc Villain Date: Mon, 2 Nov 2026 01:47:06 +0100 Subject: [PATCH] docs: package READMEs --- packages/core/README.md | 71 +++++++++++++++++++++++++++++++++++++ packages/express/README.md | 7 ++++ packages/fastify/README.md | 7 ++++ packages/mssql/README.md | 7 ++++ packages/mysql/README.md | 7 ++++ packages/postgres/README.md | 7 ++++ packages/sqlite/README.md | 7 ++++ 7 files changed, 113 insertions(+) create mode 100644 packages/core/README.md create mode 100644 packages/express/README.md create mode 100644 packages/fastify/README.md create mode 100644 packages/mssql/README.md create mode 100644 packages/mysql/README.md create mode 100644 packages/postgres/README.md create mode 100644 packages/sqlite/README.md diff --git a/packages/core/README.md b/packages/core/README.md new file mode 100644 index 0000000..cc9a9b0 --- /dev/null +++ b/packages/core/README.md @@ -0,0 +1,71 @@ +# restloom + +A REST API generated from your database's catalog. Name the schemas or tables to serve, and restloom reads their columns, types, keys and relations, and answers queries like this one: + +``` +GET /assets?select=id,name,owner(name),tags(name)&tags.name=in.(pci,gdpr)&order=owner.name.desc +``` + +```json +[ + { "id": 4, "name": "payroll db", "owner": { "name": "Linus" }, "tags": [{ "name": "pci" }, { "name": "gdpr" }] }, + { "id": 2, "name": "mail relay", "owner": { "name": "Grace" }, "tags": [{ "name": "gdpr" }] } +] +``` + +Your backend stays in charge: +- **Only what you name is served.** Nothing is exposed until a schema or table is named. +- **Writes are opt-in.** They are off until a resource enables them. +- **Sensitive columns stay hidden.** Columns named like passwords, hashes, tokens or keys are never served unless you show them on purpose. +- **Clients cannot run arbitrary queries.** They choose among what you expose: there is no query language for them to run arbitrary joins with. + +## Install + +| Package | For | +|---|---| +| `@crudy/restloom` | The core: grammar, discovery, `createREST`, a Node `http` listener | +| `@crudy/restloom-postgres` | PostgreSQL | +| `@crudy/restloom-mysql` | MySQL | +| `@crudy/restloom-mssql` | SQL Server | +| `@crudy/restloom-sqlite` | SQLite | +| `@crudy/restloom-fastify` | Fastify plugin | +| `@crudy/restloom-express` | Express handler | + +```sh +npm install @crudy/restloom @crudy/restloom-postgres pg +``` + +## Use + +```ts +import http from 'node:http'; +import pg from 'pg'; +import { createREST, nodeListener } from '@crudy/restloom'; +import { postgres } from '@crudy/restloom-postgres'; + +const rest = createREST({ + db: postgres(new pg.Pool()), + expose: { schemas: ['app'] }, + resources: { assets: { write: true } }, +}); + +http.createServer(nodeListener(rest)).listen(3000); +``` + +## Documentation + +1. [Getting started](https://github.com/crudylabs/restloom/blob/master/docs/getting-started.md) +2. [Discovery and overrides](https://github.com/crudylabs/restloom/blob/master/docs/discovery.md): what becomes a resource, hidden columns, relation names. +3. [Query grammar](https://github.com/crudylabs/restloom/blob/master/docs/query-grammar.md): select, filters, relations, order, pages, counts, aggregates. +4. [Writes and procedures](https://github.com/crudylabs/restloom/blob/master/docs/writes.md) +5. [Security and hooks](https://github.com/crudylabs/restloom/blob/master/docs/security.md) +6. [Adapters](https://github.com/crudylabs/restloom/blob/master/docs/adapters.md): Node, Fastify, Express, your own routes. +7. [Dialects](https://github.com/crudylabs/restloom/blob/master/docs/dialects.md) and [writing a dialect](https://github.com/crudylabs/restloom/blob/master/docs/writing-a-dialect.md) +8. [Errors](https://github.com/crudylabs/restloom/blob/master/docs/errors.md) +9. [Compared with PostgREST](https://github.com/crudylabs/restloom/blob/master/docs/postgrest.md) + +The examples in the grammar and writes pages are the conformance suite: each one runs against every database and must answer exactly what the page shows. + +## Licence + +Apache-2.0. diff --git a/packages/express/README.md b/packages/express/README.md new file mode 100644 index 0000000..65d97f2 --- /dev/null +++ b/packages/express/README.md @@ -0,0 +1,7 @@ +# @crudy/restloom-express + +Express adapter for restloom. See the [restloom documentation](https://restloom.crudy.fr) and the [repository](https://github.com/crudylabs/restloom). + +## Licence + +Apache-2.0. diff --git a/packages/fastify/README.md b/packages/fastify/README.md new file mode 100644 index 0000000..e188f71 --- /dev/null +++ b/packages/fastify/README.md @@ -0,0 +1,7 @@ +# @crudy/restloom-fastify + +Fastify adapter for restloom. See the [restloom documentation](https://restloom.crudy.fr) and the [repository](https://github.com/crudylabs/restloom). + +## Licence + +Apache-2.0. diff --git a/packages/mssql/README.md b/packages/mssql/README.md new file mode 100644 index 0000000..10b3dd0 --- /dev/null +++ b/packages/mssql/README.md @@ -0,0 +1,7 @@ +# @crudy/restloom-mssql + +SQL Server dialect for restloom. See the [restloom documentation](https://restloom.crudy.fr) and the [repository](https://github.com/crudylabs/restloom). + +## Licence + +Apache-2.0. diff --git a/packages/mysql/README.md b/packages/mysql/README.md new file mode 100644 index 0000000..2626aa3 --- /dev/null +++ b/packages/mysql/README.md @@ -0,0 +1,7 @@ +# @crudy/restloom-mysql + +MySQL dialect for restloom. See the [restloom documentation](https://restloom.crudy.fr) and the [repository](https://github.com/crudylabs/restloom). + +## Licence + +Apache-2.0. diff --git a/packages/postgres/README.md b/packages/postgres/README.md new file mode 100644 index 0000000..bc57040 --- /dev/null +++ b/packages/postgres/README.md @@ -0,0 +1,7 @@ +# @crudy/restloom-postgres + +Postgres dialect for restloom. See the [restloom documentation](https://restloom.crudy.fr) and the [repository](https://github.com/crudylabs/restloom). + +## Licence + +Apache-2.0. diff --git a/packages/sqlite/README.md b/packages/sqlite/README.md new file mode 100644 index 0000000..b84f6fd --- /dev/null +++ b/packages/sqlite/README.md @@ -0,0 +1,7 @@ +# @crudy/restloom-sqlite + +SQLite dialect for restloom. See the [restloom documentation](https://restloom.crudy.fr) and the [repository](https://github.com/crudylabs/restloom). + +## Licence + +Apache-2.0.