folio-db-server

Framework-agnostic fetch-style router that exposes a folio-db-next StorageAdapter over HTTP. Drop it into any runtime that speaks the web Request/Response types — Next.js route handlers, Hono, Bun, Deno, Cloudflare Workers.

Install

pnpm add folio-db-server folio-db-next

Quick start

// app/api/folio/[...path]/route.ts
import { createFolioRouter } from 'folio-db-server';
import { BlobAdapter } from 'folio-db-next/adapters/blob';

const handler = createFolioRouter({
  adapter: new BlobAdapter(),
  token: process.env.FOLIO_TOKEN!,
  basePath: '/api/folio',
});

export const GET = handler;
export const PUT = handler;
export const DELETE = handler;

Clients talk to it via folio-db-next/adapters/http:

import { createFolio } from 'folio-db-next';
import { HttpAdapter } from 'folio-db-next/adapters/http';

const folio = createFolio({
  adapter: new HttpAdapter({
    url: process.env.FOLIO_URL!,
    token: process.env.FOLIO_TOKEN!,
  }),
});

Endpoints

All routes are relative to basePath (default /api/folio).

| Method | Path | Description | |---|---|---| | GET | /health | Liveness. No auth. | | GET | /objects?prefix=... | List stored objects under a prefix. | | GET | /objects/:key | Fetch one object. 404 if missing. | | PUT | /objects/:key | Create or replace. Honours If-Match for optimistic locking — returns 409 on ETag mismatch. | | DELETE | /objects/:key | Unconditional idempotent delete. If-Match is ignored — delete has no CAS semantic; see folio issue #32. |

Keys are URL-encoded. All protected endpoints require Authorization: Bearer <token>.

Auth

• Pass a bearer token via token. The router compares verbatim.
• Pass token: null to disable auth entirely. Dev only — do not ship this to production.

Development

pnpm --filter folio-db-server build
pnpm --filter folio-db-server test
pnpm --filter folio-db-server typecheck

License

MIT.