@archlast/server 0.0.1 → 0.1.0

package/README.md

@@ -1,32 +1,801 @@
 # @archlast/server
 
-Archlast server library exports (schema, functions, types) plus Docker
-runtime metadata and templates.
+Type-safe server definitions and runtime helpers for Archlast. This package provides schema definition with validators, function definitions (query, mutation, action, http, webhook, rpc), background job scheduling, and shared types. The runtime server is delivered via Docker image.
 
-## Install
+## Table of Contents
+
+- [Installation](#installation)
+- [Library vs Runtime](#library-vs-runtime)
+- [Schema Definition](#schema-definition)
+  - [Field Types (Validators)](#field-types-validators)
+  - [Field Modifiers](#field-modifiers)
+  - [Relationships](#relationships)
+  - [Indexes](#indexes)
+- [Function Definitions](#function-definitions)
+  - [Query](#query)
+  - [Mutation](#mutation)
+  - [Action](#action)
+  - [HTTP Routes](#http-routes)
+  - [Webhooks](#webhooks)
+  - [RPC (tRPC-style)](#rpc-trpc-style)
+- [Context Objects](#context-objects)
+- [Authentication & Permissions](#authentication--permissions)
+- [Background Jobs](#background-jobs)
+- [Storage Types](#storage-types)
+- [Subpath Exports](#subpath-exports)
+- [Environment Variables](#environment-variables)
+- [Docker Templates](#docker-templates)
+
+## Installation
+
+```bash
+npm install -D @archlast/server
+
+# Or with other package managers
+pnpm add -D @archlast/server
+yarn add -D @archlast/server
+bun add -D @archlast/server
+```
+
+## Library vs Runtime
+
+This package is a **dev-time library** for schema and function definitions. The actual server runtime is delivered via Docker and managed by the CLI:
 
 ```bash
-npm install @archlast/server --save-dev
+# Use the CLI to run the server
+archlast start
+
+# The Docker image contains the full runtime
+docker pull archlast/server:latest
 ```
 
-## Library usage
+---
+
+## Schema Definition
+
+Define your data model in `src/schema.ts`:
 
 ```ts
 import { defineSchema, defineTable, v } from "@archlast/server/schema/definition";
 
 export default defineSchema({
   tasks: defineTable({
-    id: v.id(),
+    _id: v.id().primaryKey(),
     text: v.string(),
+    completed: v.boolean().default(false),
+    priority: v.string().default("medium"),
+    createdAt: v.number().createdNow(),
+    updatedAt: v.number().updateNow().optional(),
   }),
+
+  users: defineTable({
+    _id: v.id().primaryKey(),
+    email: v.string().unique(),
+    name: v.string(),
+    role: v.string().default("user"),
+  }),
+});
+```
+
+### Field Types (Validators)
+
+The `v` object provides all available field types:
+
+| Validator | TypeScript Type | Description |
+|-----------|-----------------|-------------|
+| `v.id()` | `string` | CUID2 identifier (auto-generated) |
+| `v.uuid()` | `string` | UUID v4 identifier |
+| `v.objectId()` | `string` | MongoDB-style ObjectId |
+| `v.string()` | `string` | Text field |
+| `v.number()` | `number` | Numeric field (integer or float) |
+| `v.boolean()` | `boolean` | True/false field |
+| `v.date()` | `Date` | Date object |
+| `v.datetime()` | `Date` | Date with time |
+| `v.bytes()` | `Uint8Array` | Binary data |
+| `v.json()` | `unknown` | Arbitrary JSON |
+| `v.any()` | `any` | Any type (use sparingly) |
+| `v.object(shape)` | `object` | Nested object with schema |
+| `v.array(schema)` | `T[]` | Array of items |
+| `v.optional(type)` | `T \| undefined` | Optional wrapper |
+
+### Examples
+
+```ts
+import { v } from "@archlast/server/schema/validators";
+
+// Basic types
+v.string()              // string
+v.number()              // number
+v.boolean()             // boolean
+
+// IDs
+v.id()                  // CUID2: "clxxxx..."
+v.uuid()                // UUID: "550e8400-e29b-41d4-a716-446655440000"
+v.objectId()            // ObjectId: "507f1f77bcf86cd799439011"
+
+// Dates
+v.date()                // Date object (date only)
+v.datetime()            // Date object (with time)
+
+// Complex types
+v.json()                // Any JSON-serializable value
+v.bytes()               // Binary data as Uint8Array
+
+// Nested object
+v.object({
+  street: v.string(),
+  city: v.string(),
+  zip: v.string(),
+})
+
+// Array
+v.array(v.string())           // string[]
+v.array(v.object({            // Array of objects
+  name: v.string(),
+  score: v.number(),
+}))
+```
+
+### Field Modifiers
+
+Chain modifiers to add constraints and behaviors:
+
+| Modifier | Description |
+|----------|-------------|
+| `.primaryKey()` | Mark as primary key (auto-generates if not provided) |
+| `.unique()` | Unique constraint |
+| `.index()` | Create index for faster queries |
+| `.searchable()` | Enable full-text search |
+| `.optional()` | Make field nullable (TypeScript: `T \| undefined`) |
+| `.default(value)` | Default value on insert |
+| `.createdNow()` | Auto-set to `Date.now()` on insert |
+| `.updateNow()` | Auto-set to `Date.now()` on every update |
+| `.foreignKey(table, field, options)` | Foreign key reference |
+
+### Examples
+
+```ts
+defineTable({
+  // Primary key with auto-generation
+  _id: v.id().primaryKey(),
+
+  // Unique constraint
+  email: v.string().unique(),
+
+  // Indexed for fast lookups
+  slug: v.string().index(),
+
+  // Full-text searchable
+  content: v.string().searchable(),
+
+  // Optional field
+  bio: v.string().optional(),
+
+  // Default values
+  role: v.string().default("user"),
+  count: v.number().default(0),
+  active: v.boolean().default(true),
+
+  // Automatic timestamps
+  createdAt: v.number().createdNow(),
+  updatedAt: v.number().updateNow().optional(),
+
+  // Foreign key
+  authorId: v.id().foreignKey("users", "_id", {
+    onDelete: "cascade",
+    onUpdate: "cascade",
+  }),
+})
+```
+
+### Relationships
+
+Define relationships in the second argument of `defineTable`:
+
+```ts
+import {
+  defineTable,
+  hasOne,
+  hasMany,
+  belongsTo,
+  manyToMany
+} from "@archlast/server/schema/definition";
+
+export default defineSchema({
+  users: defineTable(
+    {
+      _id: v.id().primaryKey(),
+      name: v.string(),
+    },
+    {
+      relationships: {
+        // User has many tasks
+        tasks: hasMany("tasks", "authorId"),
+
+        // User has one profile
+        profile: hasOne("profiles", "userId"),
+      },
+    }
+  ),
+
+  tasks: defineTable(
+    {
+      _id: v.id().primaryKey(),
+      text: v.string(),
+      authorId: v.id(),
+    },
+    {
+      relationships: {
+        // Task belongs to user
+        author: belongsTo("users", "authorId"),
+
+        // Task has many subtasks
+        subtasks: hasMany("subtasks", "taskId"),
+      },
+    }
+  ),
+
+  tags: defineTable(
+    {
+      _id: v.id().primaryKey(),
+      name: v.string(),
+    },
+    {
+      relationships: {
+        // Many-to-many through junction table
+        tasks: manyToMany("tasks", "task_tags", "tagId", "taskId"),
+      },
+    }
+  ),
+});
+```
+
+### Indexes
+
+Create composite indexes for complex queries:
+
+```ts
+defineTable(
+  {
+    _id: v.id().primaryKey(),
+    completed: v.boolean(),
+    priority: v.string(),
+    createdAt: v.number(),
+  },
+  {
+    indexes: [
+      // Composite index
+      { fields: ["completed", "createdAt"], name: "idx_tasks_status" },
+
+      // Single field index
+      { fields: ["priority"], name: "idx_tasks_priority" },
+    ],
+  }
+)
+```
+
+---
+
+## Function Definitions
+
+Functions are the API of your Archlast application. Import from `@archlast/server/functions/definition`.
+
+### Query
+
+Read-only operations. Results are cached and reactive.
+
+```ts
+import { query } from "@archlast/server/functions/definition";
+
+// Simple query
+export const list = query(async (ctx) => {
+  return ctx.db.query("tasks").findMany();
+});
+
+// Query with arguments
+export const get = query({
+  args: { id: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    return ctx.db.get("tasks", args.id);
+  },
+});
+
+// Query with filtering
+export const listByStatus = query({
+  args: {
+    completed: v.boolean().zodSchema,
+    limit: v.number().optional().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query("tasks")
+      .where({ completed: args.completed })
+      .take(args.limit ?? 10)
+      .findMany();
+  },
+});
+```
+
+### Mutation
+
+Write operations. Automatically invalidate related caches.
+
+```ts
+import { mutation } from "@archlast/server/functions/definition";
+
+export const create = mutation({
+  args: {
+    text: v.string().zodSchema,
+    priority: v.string().optional().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    return ctx.db.insert("tasks", {
+      text: args.text,
+      priority: args.priority ?? "medium",
+      completed: false,
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.string().zodSchema,
+    text: v.string().optional().zodSchema,
+    completed: v.boolean().optional().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    const { id, ...data } = args;
+    return ctx.db.update("tasks", id, data);
+  },
+});
+
+export const remove = mutation({
+  args: { id: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    await ctx.db.delete("tasks", args.id);
+    return { success: true };
+  },
+});
+```
+
+### Action
+
+Long-running operations, side effects, external API calls.
+
+```ts
+import { action } from "@archlast/server/functions/definition";
+
+export const sendEmail = action({
+  args: {
+    to: v.string().zodSchema,
+    subject: v.string().zodSchema,
+    body: v.string().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    // Call external email service
+    const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${process.env.SENDGRID_API_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        personalizations: [{ to: [{ email: args.to }] }],
+        from: { email: "noreply@myapp.com" },
+        subject: args.subject,
+        content: [{ type: "text/plain", value: args.body }],
+      }),
+    });
+
+    return { sent: response.ok };
+  },
+});
+
+export const processImage = action({
+  args: { storageId: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    const file = await ctx.storage.get(args.storageId);
+    // Process image...
+    const processedId = await ctx.storage.store("processed", processedBuffer);
+    return { processedId };
+  },
+});
+```
+
+### HTTP Routes
+
+Explicit HTTP endpoints with full control over request/response.
+
+```ts
+import { http } from "@archlast/server/functions/definition";
+
+// GET route
+export const health = http.get({
+  path: "/health",
+  handler: async () => {
+    return new Response("ok", { status: 200 });
+  },
+});
+
+// POST route with body parsing
+export const createWebhook = http.post({
+  path: "/api/webhooks",
+  handler: async (ctx, request) => {
+    const body = await request.json();
+    // Process webhook...
+    return Response.json({ received: true });
+  },
+});
+
+// Route with path parameters
+export const getUser = http.get({
+  path: "/api/users/:id",
+  handler: async (ctx, request, params) => {
+    const user = await ctx.db.get("users", params.id);
+    if (!user) {
+      return new Response("Not found", { status: 404 });
+    }
+    return Response.json(user);
+  },
+});
+
+// Other methods
+http.put({ path: "/api/resource/:id", handler: async (ctx, req) => { /* ... */ } });
+http.patch({ path: "/api/resource/:id", handler: async (ctx, req) => { /* ... */ } });
+http.delete({ path: "/api/resource/:id", handler: async (ctx, req) => { /* ... */ } });
+http.options({ path: "/api/resource", handler: async () => { /* ... */ } });
+```
+
+### Webhooks
+
+Signed webhook handlers with automatic verification.
+
+```ts
+import { webhook } from "@archlast/server/functions/definition";
+
+export const stripeWebhook = webhook({
+  path: "/webhooks/stripe",
+  secret: process.env.STRIPE_WEBHOOK_SECRET!,
+  handler: async (ctx, event) => {
+    switch (event.type) {
+      case "checkout.session.completed":
+        await handleCheckoutComplete(ctx, event.data);
+        break;
+      case "customer.subscription.deleted":
+        await handleSubscriptionCanceled(ctx, event.data);
+        break;
+    }
+    return { received: true };
+  },
+});
+
+export const githubWebhook = webhook({
+  path: "/webhooks/github",
+  secret: process.env.GITHUB_WEBHOOK_SECRET!,
+  signatureHeader: "X-Hub-Signature-256",
+  handler: async (ctx, payload) => {
+    console.log("GitHub event:", payload.action);
+    return { ok: true };
+  },
 });
 ```
 
-## Docker templates
+### RPC (tRPC-style)
+
+Type-safe RPC procedures with automatic router generation.
 
-Docker compose templates and configuration examples are available under
-`templates/` in this package.
+```ts
+import { rpc } from "@archlast/server/functions/definition";
+
+// RPC query
+export const getTasks = rpc.query({
+  args: { completed: v.boolean().optional().zodSchema },
+  handler: async (ctx, args) => {
+    return ctx.db.query("tasks")
+      .where(args.completed !== undefined ? { completed: args.completed } : {})
+      .findMany();
+  },
+});
 
-## Publishing (maintainers)
+// RPC mutation
+export const createTask = rpc.mutation({
+  args: { text: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    return ctx.db.insert("tasks", { text: args.text });
+  },
+});
+```
+
+---
+
+## Context Objects
+
+Each function receives a context object with available services.
+
+### QueryCtx (for queries)
+
+```ts
+interface QueryCtx {
+  db: GenericDatabaseReader<DataModel>;
+  auth: AuthContext;
+  repository: RepositoryMap<DataModel>;
+  logger: LogService;
+}
+```
+
+### MutationCtx (for mutations)
+
+```ts
+interface MutationCtx extends QueryCtx {
+  db: GenericDatabaseWriter<DataModel>;
+  scheduler: JobScheduler;
+}
+```
+
+### ActionCtx (for actions)
+
+```ts
+interface ActionCtx extends MutationCtx {
+  storage: StorageClient;
+}
+```
+
+### AuthContext
+
+```ts
+interface AuthContext {
+  userId: string | null;
+  sessionId: string | null;
+  isAuthenticated: boolean;
+  user: User | null;
+}
+```
+
+### Usage Examples
+
+```ts
+export const myQuery = query(async (ctx) => {
+  // Database access
+  const tasks = await ctx.db.query("tasks").findMany();
+
+  // LINQ-style repository
+  const data = await ctx.repository.tasks
+    .Where({ completed: false })
+    .OrderBy({ createdAt: "desc" })
+    .Take(10)
+    .ToArrayAsync();
+
+  // Auth info
+  if (ctx.auth.isAuthenticated) {
+    console.log("User:", ctx.auth.userId);
+  }
+
+  // Logging
+  ctx.logger.info("Query executed", { count: tasks.length });
+
+  return tasks;
+});
+
+export const myMutation = mutation(async (ctx) => {
+  // Schedule background job
+  await ctx.scheduler.schedule({
+    name: "sendNotification",
+    preset: SchedulePreset.RunNow,
+    payload: { userId: ctx.auth.userId },
+  });
+});
+
+export const myAction = action(async (ctx) => {
+  // File storage
+  const file = await ctx.storage.get("file_id");
+  const newId = await ctx.storage.store("bucket", buffer);
+});
+```
+
+---
+
+## Authentication & Permissions
+
+### Auth Modes
+
+All functions default to requiring authentication. Override with `auth` option:
+
+```ts
+// Required (default) - must be authenticated
+export const privateQuery = query({
+  handler: async (ctx) => {
+    // ctx.auth.userId is guaranteed to exist
+  },
+});
+
+// Optional - authentication checked but not required
+export const optionalAuth = query({
+  auth: "optional",
+  handler: async (ctx) => {
+    if (ctx.auth.isAuthenticated) {
+      // Authenticated user
+    } else {
+      // Anonymous user
+    }
+  },
+});
+
+// Public - no authentication required
+export const publicQuery = query({
+  auth: "public",
+  handler: async (ctx) => {
+    // Anyone can access
+  },
+});
+```
+
+### Permissions
+
+Add permission checks for role-based access:
+
+```ts
+export const adminOnly = query({
+  permissions: ["admin"],
+  handler: async (ctx) => {
+    // Only users with "admin" permission
+  },
+});
+
+export const moderatorOrAdmin = mutation({
+  permissions: ["admin", "moderator"],
+  handler: async (ctx) => {
+    // Users with either permission
+  },
+});
+```
+
+---
+
+## Background Jobs
+
+Schedule background tasks using the job scheduler.
+
+```ts
+import { SchedulePreset } from "@archlast/server/jobs";
+
+export const scheduleCleanup = mutation(async (ctx) => {
+  // Run immediately
+  await ctx.scheduler.schedule({
+    name: "cleanupOldRecords",
+    preset: SchedulePreset.RunNow,
+    payload: { olderThanDays: 30 },
+  });
+
+  // Run in 5 minutes
+  await ctx.scheduler.schedule({
+    name: "sendReminder",
+    preset: SchedulePreset.In5Minutes,
+    payload: { userId: ctx.auth.userId },
+  });
+
+  // Recurring with cron
+  await ctx.scheduler.schedule({
+    name: "dailyReport",
+    cron: "0 9 * * *", // Every day at 9 AM
+    payload: {},
+  });
+});
+```
+
+### Schedule Presets
+
+| Preset | Description |
+|--------|-------------|
+| `RunNow` | Execute immediately |
+| `EveryMinute` | Run every minute |
+| `Every5Minutes` | Run every 5 minutes |
+| `Every15Minutes` | Run every 15 minutes |
+| `Every30Minutes` | Run every 30 minutes |
+| `Hourly` | Run every hour |
+| `Every6Hours` | Run every 6 hours |
+| `Every12Hours` | Run every 12 hours |
+| `DailyMidnight` | Daily at midnight UTC |
+| `DailyNoon` | Daily at noon UTC |
+| `Weekly` | Weekly on Sunday midnight |
+| `Monthly` | Monthly on the 1st |
+| `In5Minutes` | Once, 5 minutes from now |
+| `In1Hour` | Once, 1 hour from now |
+| `In1Day` | Once, 24 hours from now |
+
+---
+
+## Storage Types
+
+File storage type definitions.
+
+```ts
+import type { StorageFile, StorageMetadata } from "@archlast/server/storage/types";
+
+interface StorageFile {
+  id: string;
+  bucket: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  createdAt: Date;
+}
+
+interface StorageMetadata {
+  filename: string;
+  contentType: string;
+  size: number;
+  bucket: string;
+  createdAt: Date;
+  url?: string;
+}
+```
+
+---
+
+## Subpath Exports
+
+Import only what you need:
+
+| Import | Description |
+|--------|-------------|
+| `@archlast/server/schema/definition` | `defineSchema`, `defineTable`, relationship helpers |
+| `@archlast/server/schema/validators` | `v` validator object |
+| `@archlast/server/functions/definition` | `query`, `mutation`, `action`, `http`, `webhook`, `rpc` |
+| `@archlast/server/functions/types` | Context types, function types |
+| `@archlast/server/http` | HTTP handler utilities |
+| `@archlast/server/webhook` | Webhook handler utilities |
+| `@archlast/server/jobs` | `SchedulePreset`, job types |
+| `@archlast/server/storage/types` | Storage type definitions |
+| `@archlast/server/context` | Context type exports |
+| `@archlast/server/di/*` | Dependency injection utilities |
+
+---
+
+## Environment Variables
+
+Key variables used by the server runtime:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `4000` | HTTP server port |
+| `NODE_ENV` | `development` | Environment mode |
+| `ARCHLAST_DB_ROOT` | `./data` | Database file directory |
+| `ARCHLAST_ALLOWED_ORIGINS` | - | CORS allowed origins (CSV) |
+| `ARCHLAST_CORS_ALLOW_CREDENTIALS` | `false` | Allow credentials in CORS |
+| `STORAGE_ROOT` | `./storage` | Local file storage directory |
+| `STORAGE_SIGNING_SECRET` | - | Secret for signed URLs |
+| `S3_ENABLED` | `false` | Enable S3 storage |
+| `S3_BUCKET` | - | S3 bucket name |
+| `S3_REGION` | `us-east-1` | S3 region |
+| `AWS_ACCESS_KEY_ID` | - | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | - | AWS secret key |
+| `ARCHLAST_AUTH_TOKEN_PEPPER` | - | Token signing pepper |
+| `ARCHLAST_DASHBOARD_DIR` | - | Dashboard static files path |
+| `ARCHLAST_DASHBOARD_URL` | - | Dashboard proxy URL |
+| `ARCHLAST_STORE_PORT` | `7001` | Document store port |
+| `ARCHLAST_STORE_HOST` | `127.0.0.1` | Document store host |
+| `ARCHLAST_STORE_NO_TLS` | `false` | Disable TLS for document store |
+
+---
+
+## Docker Templates
+
+Templates for Docker deployment are included in `templates/`:
+
+- `docker-compose.yml` - Base compose file
+- `docker-compose.dev.yml` - Development overrides
+- `docker-compose.prod.yml` - Production configuration
+- `.env.example` - Example environment variables
+- `archlast.config.js` - CLI configuration template
+
+The CLI uses these templates when running `archlast start`.
+
+---
+
+## Publishing (Maintainers)
 
 See `docs/npm-publishing.md` for release and publish steps.
+
+## License
+
+MIT

package/docker/README.md

@@ -1,5 +1,11 @@
 # Archlast Docker Assets
 
 This folder is reserved for Docker build assets distributed with the
-@archlast/server package. The production Dockerfile and service scripts
-are defined in the repository root under `docker/`.
+`@archlast/server` package. The production Dockerfile and s6 service
+definitions live in the repository root under `docker/`.
+
+If you are packaging a runtime image, use the root `docker/Dockerfile` and the
+service definitions in `docker/s6-rc.d/*`.
+
+For local runtime via the CLI, use the templates bundled in
+`packages/server/templates/`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/server",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "Archlast server library exports and Docker templates",
     "license": "MIT",
     "repository": {