Skip to content

SPEC.md

Latest commit

 

History

History
161 lines (119 loc) · 4.44 KB

SPEC.md

File metadata and controls

161 lines (119 loc) · 4.44 KB

Open Function Spec — SPEC v1.0

Status: Draft
Repository: github.com/aerostackdev/open-function-spec

1. Purpose

This specification defines the structural and behavioral requirements for a compliant Open Function Spec (OFS) module. A compliant module can be:

  • Installed into any OFS-compatible project via the Aerostack CLI.
  • Distributed through the Aerostack Registry or any private registry.
  • Unit-tested in a standard Node.js environment without framework dependencies.

2. Compliance Levels

Level Files Required Use Case
OFS-Full schema.ts + core.ts + adapter.ts Feature with DB + HTTP route
OFS-Core core.ts only Logic-only, no DB or HTTP
OFS-Utility core.ts only, no db access Pure utility function

3. Required File Structure

OFS-Full:

<module-name>/
  schema.ts
  core.ts
  adapter.ts
  README.md

OFS-Utility:

<module-name>/
  core.ts
  README.md

4. schema.ts Rules

  1. MUST use Drizzle ORM for all table definitions.
  2. MUST NOT contain application logic, HTTP routing, or imports from core.ts / adapter.ts.
  3. Column names MUST be snake_case. TypeScript field names MUST be camelCase via Drizzle mapping.
  4. SHOULD export inferred TypeScript types: export type T = typeof table.$inferSelect.

5. core.ts Rules

5.1 Required

  • MUST accept a CoreContext object as the first argument to all exported functions: 
    interface CoreContext {
    db: DrizzleDB;
    env?: Record<string, string>;
}
  • MUST throw standard Error instances for failures.
  • MUST return plain data objects.

5.2 Forbidden Patterns

// ❌ FORBIDDEN
import { Hono } from 'hono';
import { Request, Response } from '@cloudflare/workers-types';
return new Response(JSON.stringify(data));
process.env.STRIPE_KEY;
throw new HTTPException(400, { message: '...' });

// ✅ ALLOWED
import { eq } from 'drizzle-orm';
return rawData;
ctx.env.STRIPE_KEY;
throw new Error('Invalid input');

5.3 Runtime Portability

A compliant core.ts MUST pass unit tests in Node.js 18+ with a mock CoreContext without any worker-specific setup.

6. adapter.ts Rules

  1. MUST only import and call functions from ./core.
  2. MUST instantiate the DB client from the project's createDb() factory per request.
  3. MUST NOT contain any business logic.
  4. MUST export a named router/app.
  5. SHOULD catch Error from core.ts and map to appropriate HTTP status codes.

7. README.md Requirements

A compliant module's README.md MUST include:

  • Short description of the module's purpose.
  • Install command: npx aerostack add <slug>.
  • Table of required environment variables with descriptions.
  • List of API endpoints exposed by adapter.ts.
  • List of database tables created by schema.ts.

8. Runtime Compatibility Matrix

Runtime schema.ts client core.ts adapter.ts example
Cloudflare Workers drizzle-orm/d1 ✅ Required Hono
Node.js 18+ drizzle-orm/libsql or node-postgres ✅ Required Express
Bun drizzle-orm/libsql ✅ Required Hono or Elysia
Deno varies ✅ Best-effort —

9. Registry Manifest Schema

When published, a module is represented by the following manifest:

interface FunctionManifest {
    id: string;
    slug: string;             // URL-safe identifier, e.g. "stripe-checkout"
    name: string;             // Human readable: "Stripe Checkout"
    author: string;           // Publisher's username
    version: string;          // Semver: "1.0.0"
    type: 'feature' | 'utility';
    category: string;         // e.g. "payments", "auth", "storage"
    routeExport?: string;     // Export name from adapter.ts
    routePath?: string;       // Mount path: "/checkout"
    drizzleSchema: boolean;   // Whether module has a schema.ts
    envVars: string[];        // Required env var names
    npmDependencies: string[];// e.g. ["stripe", "zod"]
    files: Array<{
        path: string;         // "schema.ts", "core.ts", "adapter.ts"
        content: string;      // Raw source code
    }>;
}

10. Versioning

This specification follows semantic versioning:

  • MAJOR: Breaking changes to the file structure or CoreContext interface.
  • MINOR: New optional rules or runtime support additions.
  • PATCH: Clarifications and editorial changes.

Current version: 1.0.0-draft