wickedbased

Supabase DO App Spec Library - TypeScript classes for DigitalOcean App Platform infrastructure with YAML serialization support. Wicked awesome, kid.

Overview

wickedbased provides type-safe, object-oriented TypeScript classes for defining DigitalOcean App Platform resources. Replace those wicked fragile YAML templates with a robust, composable API that produces clean, properly-formatted YAML output. It's gonna be wicked pissa.

Features

Type-safe: Full TypeScript support with comprehensive type definitions
Validated: Built-in validation ensures all configurations are valid before serialization
Composable: Build complex configurations from reusable components
Pulumi Ready: Seamlessly integrates with Pulumi Outputs for runtime value resolution
Clean YAML Output: Automatic camelCase → snake_case transformation for API compatibility

Installation

npm install wickedbased
# or
pnpm add wickedbased
# or
yarn add wickedbased

Quick Start

import { Service, DockerImage, HealthCheck, EnvironmentVariable } from 'wickedbased';

// Create a service with health checks and environment variables
const service = new Service({
  name: 'rest',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 1,
  httpPort: 3000,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    registry: 'postgrest',
    repository: 'postgrest',
    tag: 'v14.2'
  }),
  healthCheck: new HealthCheck({
    httpPath: '/',
    port: 3000,
    initialDelaySeconds: 45
  }),
  envs: [
    new EnvironmentVariable({
      key: 'DATABASE_URL',
      value: 'postgresql://user:pass@db:5432/postgres',
      type: 'SECRET',
      scope: 'RUN_TIME'
    })
  ]
});

// Convert to YAML
const yaml = await service.toYAML();
console.log(yaml);

Output:

name: rest
instance_size_slug: professional-xs
instance_count: 1
http_port: 3000
source:
  registry_type: DOCKER_HUB
  registry: postgrest
  repository: postgrest
  tag: v14.2
health_check:
  http_path: /
  port: 3000
  initial_delay_seconds: 45
  period_seconds: 10
  timeout_seconds: 1
  success_threshold: 1
  failure_threshold: 3
envs:
  - key: DATABASE_URL
    value: postgresql://user:pass@db:5432/postgres
    type: SECRET
    scope: RUN_TIME

Core Classes

Service

Represents a web service that receives HTTP traffic.

import { Service, DockerImage, HealthCheck } from 'wickedbased';

const service = new Service({
  name: 'my-service',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 2,
  httpPort: 8080,
  internalPorts: [8081, 8082],
  healthCheck: new HealthCheck({
    httpPath: '/health',
    port: 8080,
    initialDelaySeconds: 30,
    periodSeconds: 10,
    timeoutSeconds: 5
  }),
  runCommand: 'npm start',
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  })
});

const yaml = await service.toYAML();

Job

Represents a one-time or scheduled task that runs to completion.

import { Job, DockerImage } from 'wickedbased';

const preDeployJob = new Job({
  name: 'migrate',
  kind: 'PRE_DEPLOY',
  runCommand: 'npx prisma migrate deploy',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 1,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  })
});

const yaml = await job.toYAML();

Worker

Represents a background worker that runs continuously without HTTP traffic.

import { Worker, DockerImage } from 'wickedbased';

const worker = new Worker({
  name: 'background-processor',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 2,
  runCommand: 'npm run worker',
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  })
});

const yaml = await worker.toYAML();

Configuration Classes

EnvironmentVariable

Environment variables with type and scope support.

const envVar = new EnvironmentVariable({
  key: 'DATABASE_URL',
  value: 'postgresql://localhost:5432/db',
  type: 'SECRET',      // GENERAL | SECRET
  scope: 'RUN_TIME'     // RUN_TIME | BUILD_TIME | DEPLOY_TIME
});

HealthCheck

Health check configuration with customizable timing parameters.

const healthCheck = new HealthCheck({
  httpPath: '/',
  port: 3000,
  initialDelaySeconds: 45,  // Wait before first check (default: 0)
  periodSeconds: 10,        // Time between checks (default: 10)
  timeoutSeconds: 10,       // Check timeout (default: 1)
  successThreshold: 1,      // Successes needed (default: 1)
  failureThreshold: 3       // Failures to mark unhealthy (default: 3)
});

DockerImage

Docker image source configuration.

// Docker Hub (without registry)
const dockerHub = new DockerImage({
  registryType: 'DOCKER_HUB',
  repository: 'nginx',
  tag: 'latest'
});

// DigitalOcean Container Registry (requires registry)
const docr = new DockerImage({
  registryType: 'DOCR',
  registry: 'my-registry',
  repository: 'my-app',
  tag: 'v1.0.0'
});

// GitHub Container Registry
const ghcr = new DockerImage({
  registryType: 'GHCR',
  repository: 'my-org/my-app',
  tag: 'main'
});

GitHubSource

GitHub repository source configuration.

const gitHubSource = new GitHubSource({
  repo: 'owner/repo',
  branch: 'main',
  sourceDir: '/',                    // Source directory (default: /)
  dockerfilePath: 'Dockerfile',      // Dockerfile path (default: Dockerfile)
  deployOnPush: false                // Auto-deploy on push (default: false)
});

Environment Variable Management

All resources (Service, Job, Worker) support environment variable management:

const service = new Service({
  name: 'my-service',
  instanceSizeSlug: 'basic-xxs',
  instanceCount: 1,
  envs: [
    new EnvironmentVariable({
      key: 'PORT',
      value: '3000'
    })
  ]
});

// Add environment variable
service.addEnv(new EnvironmentVariable({
  key: 'NODE_ENV',
  value: 'production',
  type: 'GENERAL'
}));

// Get environment variable
const port = service.getEnv('PORT');

// Remove environment variable
service.removeEnv('NODE_ENV');

// List all environment variables
const allEnvs = service.listEnvs();

Pulumi Integration

Use Pulumi Outputs for runtime value resolution:

import * as pulumi from '@pulumi/pulumi';
import { Service, DockerImage, EnvironmentVariable } from 'wickedbased';

// Assume dbUrl is a Pulumi Output from a database resource
const dbUrl = pulumi.output('postgresql://user:pass@db:5432/postgres');

const service = new Service({
  name: 'my-service',
  instanceSizeSlug: 'basic-xxs',
  instanceCount: 1,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  }),
  envs: [
    new EnvironmentVariable({
      key: 'DATABASE_URL',
      value: dbUrl,  // Pulumi Output - resolved at runtime
      type: 'SECRET',
      scope: 'RUN_TIME'
    })
  ]
});

// toYAML() automatically resolves Pulumi Outputs
const yaml = await service.toYAML();

Validation

All configurations are validated on construction:

import { ValidationError } from 'wickedbased';

try {
  const service = new Service({
    name: '',  // Empty name - will throw ValidationError
    instanceSizeSlug: 'basic-xxs',
    instanceCount: 1
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation failed for field "${error.field}": ${error.constraint}`);
    // Validation failed for field "name": must be non-empty (excluding whitespace)
  }
}

Common Validation Rules

name: Non-empty string
instanceSizeSlug: Valid DO instance size slug (e.g., 'basic-xxs', 'professional-xs')
instanceCount: Positive integer
httpPort: Integer between 1 and 65535
envs.key: Non-empty string, unique within resource
healthCheck.port: Integer between 1 and 65535
healthCheck.timing: Non-negative integers (periodSeconds, timeoutSeconds must be > 0)

Instance Size Slugs

Common DigitalOcean App Platform instance sizes:

Size	vCPUs	RAM	Transfer
basic-xxs	0.125 vCPU	256 MB	200 GB
basic-xs	0.25 vCPU	512 MB	500 GB
basic-s	0.5 vCPU	1 GB	1 TB
basic-m	1 vCPU	2 GB	2.5 TB
professional-xs	1 vCPU	2 GB	4 TB
professional-s	2 vCPU	4 GB	5 TB
professional-m	4 vCPU	8 GB	6 TB
professional-l	8 vCPU	16 GB	8 TB

Migration from YAML Templates

Before (YAML Template)

# templates/service.yaml
name: rest
instance_size_slug: professional-xs
instance_count: 1
source:
  registry_type: DOCKER_HUB
  repository: postgrest
  tag: v14.2
http_port: 3000
health_check:
  http_path: /
  port: 3000
  initial_delay_seconds: 45
envs:
  - key: DATABASE_URL
    value: "{{ .Values.database.url }}"
    type: SECRET
    scope: RUN_TIME

After (wickedbased)

import { Service, DockerImage, HealthCheck, EnvironmentVariable } from 'wickedbased';

const service = new Service({
  name: 'rest',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 1,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'postgrest',
    tag: 'v14.2'
  }),
  httpPort: 3000,
  healthCheck: new HealthCheck({
    httpPath: '/',
    port: 3000,
    initialDelaySeconds: 45
  }),
  envs: [
    new EnvironmentVariable({
      key: 'DATABASE_URL',
      value: databaseUrl,  // Direct value or Pulumi Output
      type: 'SECRET',
      scope: 'RUN_TIME'
    })
  ]
});

const yaml = await service.toYAML();

Advanced Usage

Multiple Services

import { Service, DockerImage, GitHubSource } from 'wickedbased';

const apiService = new Service({
  name: 'api',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 2,
  httpPort: 8080,
  source: new GitHubSource({
    repo: 'org/api',
    branch: 'main'
  })
});

const webService = new Service({
  name: 'web',
  instanceSizeSlug: 'basic-s',
  instanceCount: 1,
  httpPort: 80,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'nginx',
    tag: 'latest'
  })
});

const apiYaml = await apiService.toYAML();
const webYaml = await webService.toYAML();

Pre and Post Deploy Jobs

import { Job, DockerImage } from 'wickedbased';

const preDeployJob = new Job({
  name: 'migrate',
  kind: 'PRE_DEPLOY',
  runCommand: 'npx prisma migrate deploy',
  instanceSizeSlug: 'professional-xs',
  instanceCount: 1,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  })
});

const postDeployJob = new Job({
  name: 'seed',
  kind: 'POST_DEPLOY',
  runCommand: 'npm run seed',
  instanceSizeSlug: 'basic-xxs',
  instanceCount: 1,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  })
});

Volume Mounts

import { Service, DockerImage, VolumeMount } from 'wickedbased';

const service = new Service({
  name: 'data-service',
  instanceSizeSlug: 'basic-m',
  instanceCount: 1,
  source: new DockerImage({
    registryType: 'DOCKER_HUB',
    repository: 'node',
    tag: '20-alpine'
  }),
  volumes: [
    new VolumeMount({
      name: 'data',
      mountPath: '/data',
      size: 10  // Size in GB
    })
  ]
});

API Reference

Classes

Service - Web service resource
Job - One-time task resource
Worker - Background worker resource
EnvironmentVariable - Environment variable configuration
HealthCheck - Health check configuration
DockerImage - Docker image source
GitHubSource - GitHub repository source
VolumeMount - Volume mount configuration

Methods

AppPlatformResource (base class)

abstract class AppPlatformResource {
  readonly name: string;
  addEnv(env: EnvironmentVariable): void;
  removeEnv(key: string): boolean;
  getEnv(key: string): EnvironmentVariable | undefined;
  listEnvs(): readonly EnvironmentVariable[];
  abstract toJSON(): Record<string, unknown>;
  async toYAML(): Promise<string>;
}

Service

class Service extends AppPlatformResource {
  constructor(config: {
    name: string;
    instanceSizeSlug: string;
    instanceCount: number;
    httpPort?: number;
    internalPorts?: number[];
    healthCheck?: HealthCheck;
    runCommand?: string;
    volumes?: VolumeMount[];
    source?: DockerImage | GitHubSource;
    envs?: EnvironmentVariable[];
  });
}

Job

class Job extends AppPlatformResource {
  constructor(config: {
    name: string;
    kind: 'PRE_DEPLOY' | 'POST_DEPLOY';
    runCommand: string;
    instanceSizeSlug?: string;
    instanceCount?: number;
    source?: DockerImage | GitHubSource;
    envs?: EnvironmentVariable[];
  });
}

Worker

class Worker extends AppPlatformResource {
  constructor(config: {
    name: string;
    instanceSizeSlug: string;
    instanceCount: number;
    internalPorts?: number[];
    runCommand?: string;
    volumes?: VolumeMount[];
    source?: DockerImage | GitHubSource;
    envs?: EnvironmentVariable[];
  });
}

Error Handling

All validation errors throw ValidationError:

import { ValidationError } from 'wickedbased';

try {
  const service = new Service({
    name: 'test',
    instanceSizeSlug: 'basic-xxs',
    instanceCount: -1  // Invalid
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(error.field);      // 'instanceCount'
    console.error(error.value);      // -1
    console.error(error.constraint); // 'must be a positive integer'
  }
}

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT

Support

GitHub Issues: https://github.com/your-org/wickedbased/issues
Documentation: https://github.com/your-org/wickedbased/tree/main/packages/wickedbased

Changelog

See CHANGELOG.md for version history.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.commitlintrc.json		.commitlintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
test.yaml		test.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

wickedbased

Overview

Features

Installation

Quick Start

Core Classes

Service

Job

Worker

Configuration Classes

EnvironmentVariable

HealthCheck

DockerImage

GitHubSource

Environment Variable Management

Pulumi Integration

Validation

Common Validation Rules

Instance Size Slugs

Migration from YAML Templates

Before (YAML Template)

After (wickedbased)

Advanced Usage

Multiple Services

Pre and Post Deploy Jobs

Volume Mounts

API Reference

Classes

Methods

AppPlatformResource (base class)

Service

Job

Worker

Error Handling

Contributing

License

Support

Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages