@nitwel/sandbox 1.0.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nitwel/sandbox",
+  "version": "1.0.0",
+  "description": "Toolkit for spinning up directus test environments",
+  "homepage": "https://directus.io",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "sandbox": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docker"
+  ],
+  "keywords": [],
+  "type": "module",
+  "author": "Nils Twelker (nils@directus.io)",
+  "license": "MIT",
+  "private": false,
+  "devDependencies": {
+    "@directus/tsconfig": "3.0.0",
+    "@directus/utils": "13.0.9",
+    "@types/lodash-es": "4.17.12",
+    "@types/node": "22.13.14",
+    "chalk": "5.4.1",
+    "commander": "14.0.0",
+    "copyfiles": "2.4.1",
+    "get-port": "7.1.0",
+    "lodash-es": "4.17.21",
+    "pid-port": "1.0.2",
+    "tsdown": "0.14.2",
+    "tsx": "4.20.3",
+    "typedoc": "0.28.12",
+    "typedoc-plugin-markdown": "4.8.1",
+    "typescript": "5.8.3",
+    "@directus/types": "13.2.3"
+  },
+  "engines": {
+    "node": ">=12.20.0"
+  },
+  "optionalDependencies": {
+    "mysql2": "3.14.3",
+    "oracledb": "6.9.0",
+    "pg": "8.16.3",
+    "sqlite3": "5.1.7",
+    "tedious": "18.6.1"
+  },
+  "scripts": {
+    "cli": "tsx src/cli.ts",
+    "build": "tsc && copyfiles src/docker/*.yml dist -u 1",
+    "dev": "tsc -w ",
+    "build:tests": "tsdown src/index.ts  --format=esm",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --out ./docs",
+    "postinstall": "pnpm link"
+  }
+}

package/readme.md

@@ -0,0 +1,70 @@
+# Directus Api Sandbox 🛠️
+
+Utility functions for quickly spinning up and down instances of directus for usage such as testing or development.
+
+## Usage
+
+The package offers two ways of interacting, either through calling JS functions or through accessing the command line
+interface.
+
+### CLI
+
+```
+Usage: sandbox [options] <database>
+
+Arguments:
+  database                            What database to start the api with (choices: "maria", "cockroachdb", "mssql", "mysql", "oracle", "postgres", "sqlite")
+
+Options:
+  -b, --build                         Rebuild directus from source
+  -d, --dev                           Start directus in developer mode. Not compatible with build
+  -w, --watch                         Restart the api when changes are made
+  --inspect                           Start the api with debugger (default: true)
+  -p, --port <port>                   Port to start the api on
+  -x, --export                        Export the schema to a file every 2 seconds
+  -s, --schema [schema]               Load an additional schema snapshot on startup
+  --docker.basePort <dockerBasePort>  Minimum port number to use for docker containers
+  --docker.keep                       Keep containers running when stopping the sandbox
+  --docker.name                       Overwrite the name of the docker project
+  -e, --extras <extras>               Enable redis,maildev,saml or other extras
+  -i, --instances <instances>         Horizontally scale directus to a given number of instances (default: "1")
+  --killPorts                         Forcefully kills all processes that occupy ports that the api would use
+  -h, --help                          display help for command
+```
+
+### API
+
+The api is accessed through the following two functions:
+
+- [sandbox](docs/functions/sandbox.md)
+- [sandboxes](docs/functions/sandboxes.md)
+
+#### Example
+
+```ts
+import { sandbox } from '@directus/sandbox';
+
+const sb = await sandbox('postgres', { dev: true });
+
+// Interact via Rest, GQL or WebSockets
+const result = await fetch(sb.env.PUBLIC_URL + '/items/articles');
+
+console.log(await result.json());
+
+await sb.close();
+```
+
+## Inner workings
+
+Depending on what is set in the configuration, some of these steps might be skipped:
+
+1. **Building of the api**: If enabled, the api is freshly build each time the sandbox is started. Use the `watch`
+   option to quickly iterate on changes.
+2. **Starting of the docker containers**: All required docker containers like databases or extras like redis are spun up
+   and awaited until healthy. If the docker containers are still running, they will be reused instead of starting up new
+   ones.
+3. **Bootstrapping of the database**: If not already bootstrapped, the sandbox will make sure that all necessary
+   database tables are created.
+4. **Loading of a schema snapshot**: In case the `schema` option is set, the database will also the snapshot applied
+   before starting directus.
+5. **Starting of the api**: Finally, the api(s) are spun up with the right environment variables configured.