quai-types 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# quai-types
+
+Types for [Quai](https://github.com/atinseau/quai) projects.
+
+    npm install --save-dev quai-types
+
+## Functions
+
+```ts
+import { defineHandler } from "quai-types";
+
+export default defineHandler((request, response) => {
+  response.end(JSON.stringify({ path: request.url }));
+});
+```
+
+On Bun, use `defineBunHandler` and the platform's fetch-style handler:
+
+```ts
+import { defineBunHandler } from "quai-types";
+
+export default defineBunHandler((request) =>
+  Response.json({ path: new URL(request.url).pathname }),
+);
+```
+
+## Manifest
+
+`quai.toml` stays the source of truth, but `defineConfig` gives you completion
+and checking while you work out what to put in it:
+
+```ts
+import { defineConfig } from "quai-types";
+
+export default defineConfig({
+  type: "service",
+  runtime: "node",
+  service: { internalPort: 8080, start: "node server.js" },
+  limits: { memory: "512Mi", cpu: "1" },
+});
+```
+
+Every helper returns its argument untouched. They exist for the type checker,
+so the code that runs on the server is exactly the code you wrote.
+

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Types for Quai projects.
+ *
+ * Everything here exists for the type checker and the editor. The helpers
+ * return their argument untouched: a wrapper would make the code that runs on
+ * the server differ from the code that was written, which is exactly what a
+ * typing package should not do.
+ */
+/**
+ * The Node request and response, described structurally rather than imported.
+ *
+ * Importing node:http would force @types/node on everyone, including projects
+ * that only deploy a static site or a Bun function. The shape below is what a
+ * handler actually uses; a real IncomingMessage satisfies it.
+ */
+export type QuaiRequest = {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: string, listener: (...args: never[]) => void): unknown;
+};
+export type QuaiResponse = {
+    statusCode: number;
+    setHeader(name: string, value: string | number | readonly string[]): unknown;
+    end(body?: string | Uint8Array): unknown;
+    write(chunk: string | Uint8Array): unknown;
+};
+/**
+ * A Node function.
+ *
+ * Quai supplies the server; the handler decides what a request produces. It
+ * may be exported as `default` or as `handler`.
+ */
+export type QuaiHandler = (request: QuaiRequest, response: QuaiResponse) => void | Promise<void>;
+/** A Bun function, written against the platform's fetch-style handler. */
+export type QuaiBunHandler = (request: Request) => Response | Promise<Response>;
+/** Identity at runtime; it is the type annotation that does the work. */
+export declare function defineHandler(handler: QuaiHandler): QuaiHandler;
+/** Identity at runtime, as above. */
+export declare function defineBunHandler(handler: QuaiBunHandler): QuaiBunHandler;
+export type ProjectType = "static" | "service" | "function";
+export type Runtime = "node" | "bun" | "python";
+export type QuaiConfig = {
+    /** Defaults to the directory name, which is what makes redeploys idempotent. */
+    name?: string;
+    type: ProjectType;
+    runtime?: Runtime;
+    /** Runs on your machine. Only the output is uploaded. */
+    build?: {
+        command?: string;
+        /** Directory to ship instead of the whole project. */
+        output?: string;
+    };
+    service?: {
+        /** Declared, never guessed: the process listens where it says it does. */
+        internalPort?: number;
+        start?: string;
+    };
+    limits?: {
+        /** e.g. "256Mi", "1Gi". Absent means Quai's default. */
+        memory?: string;
+        /** Fraction of a core, e.g. "0.5". */
+        cpu?: string;
+        /** Maximum processes; this is what stops a fork bomb. */
+        pids?: number;
+        disk?: string;
+        /** Functions only, e.g. "30s". */
+        timeout?: string;
+    };
+    domains?: {
+        /** Served alongside the automatic subdomain, never instead of it. */
+        custom?: string[];
+    };
+    env?: Record<string, string>;
+};
+/** Identity at runtime; use it to get completion and checking on a manifest. */
+export declare function defineConfig(config: QuaiConfig): QuaiConfig;

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Types for Quai projects.
+ *
+ * Everything here exists for the type checker and the editor. The helpers
+ * return their argument untouched: a wrapper would make the code that runs on
+ * the server differ from the code that was written, which is exactly what a
+ * typing package should not do.
+ */
+/** Identity at runtime; it is the type annotation that does the work. */
+export function defineHandler(handler) {
+    return handler;
+}
+/** Identity at runtime, as above. */
+export function defineBunHandler(handler) {
+    return handler;
+}
+/** Identity at runtime; use it to get completion and checking on a manifest. */
+export function defineConfig(config) {
+    return config;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "quai-types",
+  "version": "0.1.0",
+  "description": "Types for Quai projects: handlers and quai.toml",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atinseau/quai.git",
+    "directory": "packages/quai"
+  },
+  "keywords": [
+    "quai",
+    "paas",
+    "self-hosted",
+    "coolify",
+    "types"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}