feat: add typed compose object support

Add a `compose` option to `IDockerComposeOptions` that accepts a
typed `ComposeSpecification` object. The object is serialized to YAML
internally and piped via stdin using the existing `configAsString` path.

TypeScript types are generated from the official Compose Specification
JSON Schema (Apache 2.0) using json-schema-to-typescript.

Author: AlexZeitler

docs/api.md

@@ -70,6 +70,7 @@ compose.upAll({
 | `executablePath` | `string` | Path to docker-compose executable if not in `$PATH` |
 | `config` | `string \| string[]` | Custom yml file(s), relative to `cwd` |
 | `configAsString` | `string` | Configuration as string (ignores `config` if set) |
+| `compose` | `ComposeSpecification` | Typed compose configuration object (converted to YAML internally) |
 | `log` | `boolean` | Enable console logging |
 | `composeOptions` | `string[] \| Array<string \| string[]>` | Options for all commands (e.g., `--verbose`) |
 | `commandOptions` | `string[] \| Array<string \| string[]>` | Options for specific command |
@@ -89,3 +90,30 @@ compose.upAll({
   commandOptions: ['--build', ['--timeout', '30']]
 })
 ```
+
+### Example with typed compose object
+
+Instead of using a YAML file, you can pass a typed `ComposeSpecification` object directly. This gives you full TypeScript autocompletion and type checking for the Docker Compose configuration.
+
+```typescript
+import { upAll, ComposeSpecification } from 'docker-compose'
+
+const compose: ComposeSpecification = {
+  services: {
+    web: {
+      image: 'nginx:latest',
+      ports: ['8080:80']
+    },
+    db: {
+      image: 'postgres:16',
+      environment: {
+        POSTGRES_PASSWORD: 'secret'
+      }
+    }
+  }
+}
+
+await upAll({ compose })
+```
+
+The `ComposeSpecification` type is generated from the official [Compose Specification JSON Schema](https://github.com/compose-spec/compose-spec), so it covers all valid compose file options.

package.json

@@ -8,8 +8,9 @@
     "ci": "yarn install --frozen-lockfile",
     "test": "npx vitest --dir test --test-timeout=30000",
     "lint": "eslint src/**/*.ts test/**/*.ts",
-    "build": "tsc",
-    "prepublishOnly": "tsc",
+    "generate:types": "json2ts schema/compose-spec.json src/compose-spec.d.ts",
+    "build": "yarn generate:types && tsc",
+    "prepublishOnly": "yarn generate:types && tsc",
     "release": "yarn build && standard-version"
   },
   "repository": {
@@ -94,6 +95,7 @@
     "eslint-plugin-prettier": "^3.3.1",
     "eslint-watch": "^7.0.0",
     "husky": "^6.0.0",
+    "json-schema-to-typescript": "^15.0.4",
     "prettier": "^2.2.1",
     "standard-version": "9.5.0",
     "typescript": "^5.0.0",

schema/NOTICE

@@ -0,0 +1,6 @@
+The file compose-spec.json is sourced from the Compose Specification project:
+https://github.com/compose-spec/compose-go
+
+Copyright The Compose Specification Authors.
+Licensed under the Apache License, Version 2.0.
+See https://www.apache.org/licenses/LICENSE-2.0