@sonicjs-cms/core 3.0.0-beta.22 → 3.0.0-beta.24

package/dist/adapters.d.cts

@@ -0,0 +1,342 @@
+import Database from 'better-sqlite3';
+import { Hono } from 'hono';
+
+/**
+ * Runtime SQLite driver — D1Database-compatible adapter backed by better-sqlite3.
+ *
+ * Designed for Tier 1 self-hosted deployments (Docker, VPS, Node/Bun).
+ * The Cloudflare Workers path never imports this file.
+ *
+ * Usage:
+ *   import { createSqliteDriver } from '@sonicjs-cms/core/adapters'
+ *   const db = await createSqliteDriver('./data/sonicjs.db')
+ *   // Pass `db` anywhere SonicJS expects a D1Database binding.
+ */
+
+type BindValue = number | string | bigint | Buffer | null;
+interface D1Meta {
+    duration: number;
+    size_after?: number;
+    rows_read: number;
+    rows_written: number;
+    last_row_id: number;
+    changed_db: boolean;
+    changes: number;
+}
+interface D1Result<T = unknown> {
+    results: T[];
+    success: boolean;
+    meta: D1Meta;
+}
+declare class SqliteStatement {
+    private readonly sqlite;
+    private readonly sql;
+    private readonly binds;
+    constructor(sqlite: Database.Database, sql: string, binds?: BindValue[]);
+    bind(...args: unknown[]): SqliteStatement;
+    run(): Promise<D1Result<never>>;
+    all<T = unknown>(): Promise<D1Result<T>>;
+    first<T = unknown>(colName?: string): Promise<T | null>;
+    raw<T = unknown[]>(): Promise<T[]>;
+    execInBatch(): void;
+}
+interface SqliteDriver {
+    prepare(sql: string): SqliteStatement;
+    batch<T = unknown>(statements: SqliteStatement[]): Promise<Array<D1Result<T>>>;
+    exec(query: string): Promise<{
+        count: number;
+        duration: number;
+    }>;
+    dump(): Promise<ArrayBuffer>;
+    /** Close the underlying database file handle (for graceful shutdown). */
+    close(): void;
+    /** Path passed at creation time (`:memory:` for in-memory). */
+    readonly path: string;
+}
+interface SqliteDriverOptions {
+    /**
+     * Absolute or relative path to the SQLite database file, or `:memory:` for
+     * an in-memory database.  Defaults to `:memory:`.
+     */
+    dbPath?: string;
+    /**
+     * When true, applies the bundled SonicJS migrations (0001_core.sql,
+     * 0002_documents.sql) before returning.  Defaults to true when the DB does
+     * not yet contain the `auth_user` table (i.e. first boot).
+     * Set to false if you manage migrations yourself via an external tool.
+     */
+    autoMigrate?: boolean;
+    /**
+     * Directory that contains the *.sql migration files.  Defaults to the
+     * migrations/ folder bundled with `@sonicjs-cms/core`.
+     */
+    migrationsPath?: string;
+}
+/**
+ * Create a D1Database-compatible SQLite driver for self-hosted deployments.
+ *
+ * ```ts
+ * const db = await createSqliteDriver({ dbPath: './data/sonicjs.db' })
+ * // db satisfies D1Database — pass it directly as c.env.DB
+ * ```
+ */
+declare function createSqliteDriver(options?: SqliteDriverOptions): Promise<SqliteDriver>;
+
+/**
+ * Filesystem storage driver — R2Bucket-compatible adapter for self-hosted deployments.
+ *
+ * Files land at `{storageDir}/{key}` preserving path structure.
+ * Metadata (httpMetadata + customMetadata) is stored alongside as `{key}.meta.json`.
+ *
+ * Usage:
+ *   import { createFilesystemDriver } from '@sonicjs-cms/core/adapters'
+ *   const bucket = createFilesystemDriver('./data/media')
+ *   // Pass `bucket` anywhere SonicJS expects the MEDIA_BUCKET R2Bucket binding.
+ */
+interface R2HttpMetadata {
+    contentType?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    cacheControl?: string;
+    cacheExpiry?: Date;
+}
+interface R2StoredMeta {
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+}
+interface R2ObjectBody {
+    key: string;
+    size: number;
+    etag: string;
+    httpMetadata: R2HttpMetadata;
+    customMetadata: Record<string, string>;
+    /** Web-standard ReadableStream over the file contents. */
+    body: ReadableStream;
+    /** Convenience: consume as ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Convenience: consume as text. */
+    text(): Promise<string>;
+}
+interface R2ObjectInfo {
+    key: string;
+    size: number;
+    etag: string;
+    httpMetadata: R2HttpMetadata;
+    customMetadata: Record<string, string>;
+}
+interface PutOptions {
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+}
+interface StorageDriver {
+    put(key: string, value: ArrayBuffer | ReadableStream | Blob | ArrayBufferView | string, options?: PutOptions): Promise<R2ObjectInfo>;
+    get(key: string): Promise<R2ObjectBody | null>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<R2ObjectInfo | null>;
+}
+/**
+ * Create an R2Bucket-compatible filesystem storage driver.
+ *
+ * ```ts
+ * const bucket = createFilesystemDriver('./data/media')
+ * // bucket satisfies R2Bucket — pass it as c.env.MEDIA_BUCKET
+ * ```
+ *
+ * @param storageDir  Absolute or relative path to the root storage directory.
+ *                    Created automatically if it doesn't exist.
+ */
+declare function createFilesystemDriver(storageDir: string): StorageDriver;
+
+/**
+ * In-memory KV driver — KVNamespace-compatible adapter for self-hosted deployments.
+ *
+ * Values survive the process lifetime. For cross-restart persistence, wire the
+ * optional `persistPath` to a JSON file; entries are written on every put/delete.
+ *
+ * Usage:
+ *   import { createMemoryKVDriver } from '@sonicjs-cms/core/adapters'
+ *   const kv = createMemoryKVDriver()
+ *   // Pass `kv` anywhere SonicJS expects a KVNamespace (CACHE_KV binding).
+ */
+interface KVPutOptions {
+    expirationTtl?: number;
+    /** Absolute Unix timestamp (seconds) at which the key expires. */
+    expiration?: number;
+    metadata?: unknown;
+}
+interface KVListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface KVListResult {
+    keys: Array<{
+        name: string;
+        expiration?: number;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+}
+interface KVGetWithMetadata<T> {
+    value: T | null;
+    metadata: unknown;
+}
+interface KVDriver {
+    get(key: string): Promise<string | null>;
+    get(key: string, type: 'text'): Promise<string | null>;
+    get<T = unknown>(key: string, type: 'json'): Promise<T | null>;
+    get(key: string, type: 'arrayBuffer'): Promise<ArrayBuffer | null>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: KVPutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: KVListOptions): Promise<KVListResult>;
+    getWithMetadata<T = unknown>(key: string, type: 'json'): Promise<KVGetWithMetadata<T>>;
+}
+interface MemoryKVOptions {
+    /**
+     * Path to a JSON file used for persistence across restarts.
+     * The file is read on startup and written on every put/delete.
+     * Omit for a pure in-memory (ephemeral) store.
+     */
+    persistPath?: string;
+}
+declare function createMemoryKVDriver(options?: MemoryKVOptions): KVDriver;
+
+/**
+ * Synchronous Queue driver — Cloudflare Queue-compatible adapter for self-hosted deployments.
+ *
+ * Instead of enqueuing messages to a remote queue, `send()` immediately invokes
+ * the registered handler in-process. This means "queued" work (e.g. scheduled
+ * email jobs) runs synchronously before the HTTP response is returned — acceptable
+ * for low-volume self-host deployments.
+ *
+ * Usage:
+ *   import { createSyncQueueDriver } from '@sonicjs-cms/core/adapters'
+ *
+ *   const emailQueue = createSyncQueueDriver(async (messages) => {
+ *     // same body as handleEmailQueueMessage() from email-templates-plugin
+ *     for (const msg of messages) {
+ *       await processJob(msg.body)
+ *       msg.ack()
+ *     }
+ *   })
+ *   // Pass emailQueue as c.env.EMAIL_QUEUE
+ */
+interface QueueMessage<T = unknown> {
+    id: string;
+    body: T;
+    timestamp: Date;
+    ack(): void;
+    retry(): void;
+}
+interface MessageBatch<T = unknown> {
+    readonly queue: string;
+    readonly messages: QueueMessage<T>[];
+    ackAll(): void;
+    retryAll(): void;
+}
+interface SendOptions {
+    delaySeconds?: number;
+    contentType?: string;
+}
+type QueueHandler<T> = (batch: MessageBatch<T>) => Promise<void>;
+interface QueueDriver<T = unknown> {
+    /**
+     * Send a message. The registered handler is invoked synchronously (after
+     * `delaySeconds` have elapsed when non-zero, via a non-blocking `setTimeout`).
+     */
+    send(body: T, options?: SendOptions): Promise<void>;
+    /**
+     * Send many messages in a single batch.
+     */
+    sendBatch(messages: Array<{
+        body: T;
+        options?: SendOptions;
+    }>): Promise<void>;
+}
+/**
+ * Create a synchronous Queue driver.
+ *
+ * @param handler   Called for each message (or batch). When `handler` is omitted,
+ *                  messages are logged and discarded — useful when EMAIL_QUEUE is
+ *                  optional and no handler is wired yet.
+ * @param queueName Optional queue name shown in MessageBatch (cosmetic).
+ */
+declare function createSyncQueueDriver<T = unknown>(handler?: QueueHandler<T>, queueName?: string): QueueDriver<T>;
+
+/**
+ * Node / Bun server adapter for self-hosted SonicJS deployments.
+ *
+ * Wires the local SQLite DB driver, filesystem storage, in-memory KV, and
+ * optional sync queue into a SonicJS app so it can run outside Cloudflare Workers.
+ *
+ * ## Quick start (Node.js)
+ *
+ * ```ts
+ * import { serve } from '@hono/node-server'
+ * import { createSonicJSApp } from '@sonicjs-cms/core'
+ * import { createNodeSonicApp } from '@sonicjs-cms/core/adapters'
+ *
+ * const app = createSonicJSApp({ ... })
+ * const adapted = await createNodeSonicApp(app, {
+ *   dbPath: './data/sonicjs.db',
+ *   storagePath: './data/media',
+ * })
+ * serve({ fetch: adapted.fetch, port: 3000 })
+ * ```
+ *
+ * ## Quick start (Bun)
+ *
+ * ```ts
+ * import { createSonicJSApp } from '@sonicjs-cms/core'
+ * import { createNodeSonicApp } from '@sonicjs-cms/core/adapters'
+ *
+ * const app = createSonicJSApp({ ... })
+ * const adapted = await createNodeSonicApp(app, {
+ *   dbPath: './data/sonicjs.db',
+ *   storagePath: './data/media',
+ * })
+ * Bun.serve({ fetch: adapted.fetch, port: 3000 })
+ * ```
+ */
+
+interface NodeAdapterOptions {
+    /**
+     * Path to the SQLite database file.
+     * Defaults to `./data/sonicjs.db`.
+     */
+    dbPath?: string;
+    /**
+     * Root directory for uploaded media files (replaces R2).
+     * Defaults to `./data/media`.
+     */
+    storagePath?: string;
+    /**
+     * Path to a JSON file used to persist KV entries across restarts.
+     * Omit for ephemeral in-memory KV (TTL-based caching only).
+     */
+    kvPersistPath?: string;
+    /**
+     * Environment variables injected as `c.env.*` (JWT_SECRET, CORS_ORIGINS, etc.).
+     * Values are merged with process.env so you can also use dotenv.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Wrap a SonicJS Hono app with local adapter bindings injected before any
+ * SonicJS middleware (bootstrap, auth, routes) executes.
+ *
+ * The injection MUST run first — SonicJS's bootstrap middleware accesses
+ * `c.env.DB` on the very first request. If we append the middleware after
+ * `createSonicJSApp()` we'd lose the ordering race. Instead we wrap the
+ * sonicApp in a fresh Hono instance that injects env first, then routes
+ * all requests through the sonicApp.
+ *
+ * @param sonicApp The SonicJS Hono app created by `createSonicJSApp()`.
+ * @param options  Adapter configuration.
+ */
+declare function createNodeSonicApp<E extends {
+    Bindings: Record<string, unknown>;
+}>(sonicApp: Hono<E>, options?: NodeAdapterOptions): Promise<Hono<E>>;
+
+export { type KVDriver, type KVGetWithMetadata, type KVListOptions, type KVListResult, type KVPutOptions, type MemoryKVOptions, type MessageBatch, type NodeAdapterOptions, type PutOptions, type QueueDriver, type QueueHandler, type QueueMessage, type R2HttpMetadata, type R2ObjectBody, type R2ObjectInfo, type R2StoredMeta, type SendOptions, type SqliteDriver, type SqliteDriverOptions, type StorageDriver, createFilesystemDriver, createMemoryKVDriver, createNodeSonicApp, createSqliteDriver, createSyncQueueDriver };

package/dist/adapters.d.ts

@@ -0,0 +1,342 @@
+import Database from 'better-sqlite3';
+import { Hono } from 'hono';
+
+/**
+ * Runtime SQLite driver — D1Database-compatible adapter backed by better-sqlite3.
+ *
+ * Designed for Tier 1 self-hosted deployments (Docker, VPS, Node/Bun).
+ * The Cloudflare Workers path never imports this file.
+ *
+ * Usage:
+ *   import { createSqliteDriver } from '@sonicjs-cms/core/adapters'
+ *   const db = await createSqliteDriver('./data/sonicjs.db')
+ *   // Pass `db` anywhere SonicJS expects a D1Database binding.
+ */
+
+type BindValue = number | string | bigint | Buffer | null;
+interface D1Meta {
+    duration: number;
+    size_after?: number;
+    rows_read: number;
+    rows_written: number;
+    last_row_id: number;
+    changed_db: boolean;
+    changes: number;
+}
+interface D1Result<T = unknown> {
+    results: T[];
+    success: boolean;
+    meta: D1Meta;
+}
+declare class SqliteStatement {
+    private readonly sqlite;
+    private readonly sql;
+    private readonly binds;
+    constructor(sqlite: Database.Database, sql: string, binds?: BindValue[]);
+    bind(...args: unknown[]): SqliteStatement;
+    run(): Promise<D1Result<never>>;
+    all<T = unknown>(): Promise<D1Result<T>>;
+    first<T = unknown>(colName?: string): Promise<T | null>;
+    raw<T = unknown[]>(): Promise<T[]>;
+    execInBatch(): void;
+}
+interface SqliteDriver {
+    prepare(sql: string): SqliteStatement;
+    batch<T = unknown>(statements: SqliteStatement[]): Promise<Array<D1Result<T>>>;
+    exec(query: string): Promise<{
+        count: number;
+        duration: number;
+    }>;
+    dump(): Promise<ArrayBuffer>;
+    /** Close the underlying database file handle (for graceful shutdown). */
+    close(): void;
+    /** Path passed at creation time (`:memory:` for in-memory). */
+    readonly path: string;
+}
+interface SqliteDriverOptions {
+    /**
+     * Absolute or relative path to the SQLite database file, or `:memory:` for
+     * an in-memory database.  Defaults to `:memory:`.
+     */
+    dbPath?: string;
+    /**
+     * When true, applies the bundled SonicJS migrations (0001_core.sql,
+     * 0002_documents.sql) before returning.  Defaults to true when the DB does
+     * not yet contain the `auth_user` table (i.e. first boot).
+     * Set to false if you manage migrations yourself via an external tool.
+     */
+    autoMigrate?: boolean;
+    /**
+     * Directory that contains the *.sql migration files.  Defaults to the
+     * migrations/ folder bundled with `@sonicjs-cms/core`.
+     */
+    migrationsPath?: string;
+}
+/**
+ * Create a D1Database-compatible SQLite driver for self-hosted deployments.
+ *
+ * ```ts
+ * const db = await createSqliteDriver({ dbPath: './data/sonicjs.db' })
+ * // db satisfies D1Database — pass it directly as c.env.DB
+ * ```
+ */
+declare function createSqliteDriver(options?: SqliteDriverOptions): Promise<SqliteDriver>;
+
+/**
+ * Filesystem storage driver — R2Bucket-compatible adapter for self-hosted deployments.
+ *
+ * Files land at `{storageDir}/{key}` preserving path structure.
+ * Metadata (httpMetadata + customMetadata) is stored alongside as `{key}.meta.json`.
+ *
+ * Usage:
+ *   import { createFilesystemDriver } from '@sonicjs-cms/core/adapters'
+ *   const bucket = createFilesystemDriver('./data/media')
+ *   // Pass `bucket` anywhere SonicJS expects the MEDIA_BUCKET R2Bucket binding.
+ */
+interface R2HttpMetadata {
+    contentType?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    cacheControl?: string;
+    cacheExpiry?: Date;
+}
+interface R2StoredMeta {
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+}
+interface R2ObjectBody {
+    key: string;
+    size: number;
+    etag: string;
+    httpMetadata: R2HttpMetadata;
+    customMetadata: Record<string, string>;
+    /** Web-standard ReadableStream over the file contents. */
+    body: ReadableStream;
+    /** Convenience: consume as ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Convenience: consume as text. */
+    text(): Promise<string>;
+}
+interface R2ObjectInfo {
+    key: string;
+    size: number;
+    etag: string;
+    httpMetadata: R2HttpMetadata;
+    customMetadata: Record<string, string>;
+}
+interface PutOptions {
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+}
+interface StorageDriver {
+    put(key: string, value: ArrayBuffer | ReadableStream | Blob | ArrayBufferView | string, options?: PutOptions): Promise<R2ObjectInfo>;
+    get(key: string): Promise<R2ObjectBody | null>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<R2ObjectInfo | null>;
+}
+/**
+ * Create an R2Bucket-compatible filesystem storage driver.
+ *
+ * ```ts
+ * const bucket = createFilesystemDriver('./data/media')
+ * // bucket satisfies R2Bucket — pass it as c.env.MEDIA_BUCKET
+ * ```
+ *
+ * @param storageDir  Absolute or relative path to the root storage directory.
+ *                    Created automatically if it doesn't exist.
+ */
+declare function createFilesystemDriver(storageDir: string): StorageDriver;
+
+/**
+ * In-memory KV driver — KVNamespace-compatible adapter for self-hosted deployments.
+ *
+ * Values survive the process lifetime. For cross-restart persistence, wire the
+ * optional `persistPath` to a JSON file; entries are written on every put/delete.
+ *
+ * Usage:
+ *   import { createMemoryKVDriver } from '@sonicjs-cms/core/adapters'
+ *   const kv = createMemoryKVDriver()
+ *   // Pass `kv` anywhere SonicJS expects a KVNamespace (CACHE_KV binding).
+ */
+interface KVPutOptions {
+    expirationTtl?: number;
+    /** Absolute Unix timestamp (seconds) at which the key expires. */
+    expiration?: number;
+    metadata?: unknown;
+}
+interface KVListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface KVListResult {
+    keys: Array<{
+        name: string;
+        expiration?: number;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+}
+interface KVGetWithMetadata<T> {
+    value: T | null;
+    metadata: unknown;
+}
+interface KVDriver {
+    get(key: string): Promise<string | null>;
+    get(key: string, type: 'text'): Promise<string | null>;
+    get<T = unknown>(key: string, type: 'json'): Promise<T | null>;
+    get(key: string, type: 'arrayBuffer'): Promise<ArrayBuffer | null>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: KVPutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: KVListOptions): Promise<KVListResult>;
+    getWithMetadata<T = unknown>(key: string, type: 'json'): Promise<KVGetWithMetadata<T>>;
+}
+interface MemoryKVOptions {
+    /**
+     * Path to a JSON file used for persistence across restarts.
+     * The file is read on startup and written on every put/delete.
+     * Omit for a pure in-memory (ephemeral) store.
+     */
+    persistPath?: string;
+}
+declare function createMemoryKVDriver(options?: MemoryKVOptions): KVDriver;
+
+/**
+ * Synchronous Queue driver — Cloudflare Queue-compatible adapter for self-hosted deployments.
+ *
+ * Instead of enqueuing messages to a remote queue, `send()` immediately invokes
+ * the registered handler in-process. This means "queued" work (e.g. scheduled
+ * email jobs) runs synchronously before the HTTP response is returned — acceptable
+ * for low-volume self-host deployments.
+ *
+ * Usage:
+ *   import { createSyncQueueDriver } from '@sonicjs-cms/core/adapters'
+ *
+ *   const emailQueue = createSyncQueueDriver(async (messages) => {
+ *     // same body as handleEmailQueueMessage() from email-templates-plugin
+ *     for (const msg of messages) {
+ *       await processJob(msg.body)
+ *       msg.ack()
+ *     }
+ *   })
+ *   // Pass emailQueue as c.env.EMAIL_QUEUE
+ */
+interface QueueMessage<T = unknown> {
+    id: string;
+    body: T;
+    timestamp: Date;
+    ack(): void;
+    retry(): void;
+}
+interface MessageBatch<T = unknown> {
+    readonly queue: string;
+    readonly messages: QueueMessage<T>[];
+    ackAll(): void;
+    retryAll(): void;
+}
+interface SendOptions {
+    delaySeconds?: number;
+    contentType?: string;
+}
+type QueueHandler<T> = (batch: MessageBatch<T>) => Promise<void>;
+interface QueueDriver<T = unknown> {
+    /**
+     * Send a message. The registered handler is invoked synchronously (after
+     * `delaySeconds` have elapsed when non-zero, via a non-blocking `setTimeout`).
+     */
+    send(body: T, options?: SendOptions): Promise<void>;
+    /**
+     * Send many messages in a single batch.
+     */
+    sendBatch(messages: Array<{
+        body: T;
+        options?: SendOptions;
+    }>): Promise<void>;
+}
+/**
+ * Create a synchronous Queue driver.
+ *
+ * @param handler   Called for each message (or batch). When `handler` is omitted,
+ *                  messages are logged and discarded — useful when EMAIL_QUEUE is
+ *                  optional and no handler is wired yet.
+ * @param queueName Optional queue name shown in MessageBatch (cosmetic).
+ */
+declare function createSyncQueueDriver<T = unknown>(handler?: QueueHandler<T>, queueName?: string): QueueDriver<T>;
+
+/**
+ * Node / Bun server adapter for self-hosted SonicJS deployments.
+ *
+ * Wires the local SQLite DB driver, filesystem storage, in-memory KV, and
+ * optional sync queue into a SonicJS app so it can run outside Cloudflare Workers.
+ *
+ * ## Quick start (Node.js)
+ *
+ * ```ts
+ * import { serve } from '@hono/node-server'
+ * import { createSonicJSApp } from '@sonicjs-cms/core'
+ * import { createNodeSonicApp } from '@sonicjs-cms/core/adapters'
+ *
+ * const app = createSonicJSApp({ ... })
+ * const adapted = await createNodeSonicApp(app, {
+ *   dbPath: './data/sonicjs.db',
+ *   storagePath: './data/media',
+ * })
+ * serve({ fetch: adapted.fetch, port: 3000 })
+ * ```
+ *
+ * ## Quick start (Bun)
+ *
+ * ```ts
+ * import { createSonicJSApp } from '@sonicjs-cms/core'
+ * import { createNodeSonicApp } from '@sonicjs-cms/core/adapters'
+ *
+ * const app = createSonicJSApp({ ... })
+ * const adapted = await createNodeSonicApp(app, {
+ *   dbPath: './data/sonicjs.db',
+ *   storagePath: './data/media',
+ * })
+ * Bun.serve({ fetch: adapted.fetch, port: 3000 })
+ * ```
+ */
+
+interface NodeAdapterOptions {
+    /**
+     * Path to the SQLite database file.
+     * Defaults to `./data/sonicjs.db`.
+     */
+    dbPath?: string;
+    /**
+     * Root directory for uploaded media files (replaces R2).
+     * Defaults to `./data/media`.
+     */
+    storagePath?: string;
+    /**
+     * Path to a JSON file used to persist KV entries across restarts.
+     * Omit for ephemeral in-memory KV (TTL-based caching only).
+     */
+    kvPersistPath?: string;
+    /**
+     * Environment variables injected as `c.env.*` (JWT_SECRET, CORS_ORIGINS, etc.).
+     * Values are merged with process.env so you can also use dotenv.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Wrap a SonicJS Hono app with local adapter bindings injected before any
+ * SonicJS middleware (bootstrap, auth, routes) executes.
+ *
+ * The injection MUST run first — SonicJS's bootstrap middleware accesses
+ * `c.env.DB` on the very first request. If we append the middleware after
+ * `createSonicJSApp()` we'd lose the ordering race. Instead we wrap the
+ * sonicApp in a fresh Hono instance that injects env first, then routes
+ * all requests through the sonicApp.
+ *
+ * @param sonicApp The SonicJS Hono app created by `createSonicJSApp()`.
+ * @param options  Adapter configuration.
+ */
+declare function createNodeSonicApp<E extends {
+    Bindings: Record<string, unknown>;
+}>(sonicApp: Hono<E>, options?: NodeAdapterOptions): Promise<Hono<E>>;
+
+export { type KVDriver, type KVGetWithMetadata, type KVListOptions, type KVListResult, type KVPutOptions, type MemoryKVOptions, type MessageBatch, type NodeAdapterOptions, type PutOptions, type QueueDriver, type QueueHandler, type QueueMessage, type R2HttpMetadata, type R2ObjectBody, type R2ObjectInfo, type R2StoredMeta, type SendOptions, type SqliteDriver, type SqliteDriverOptions, type StorageDriver, createFilesystemDriver, createMemoryKVDriver, createNodeSonicApp, createSqliteDriver, createSyncQueueDriver };