@jvelo/tapemark 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,504 @@
+import { Child } from 'hono/jsx';
+import { JSX } from 'hono/jsx/jsx-dev-runtime';
+
+/** Result returned by an action handler. Surfaced as a flash message. */
+export declare interface ActionResult {
+    success: boolean;
+    message?: string;
+}
+
+export declare const builtinDisplayTypes: Record<string, DisplayType>;
+
+export declare function castValue(value: string, column: Column): CellValue;
+
+export declare type CellValue = string | number | null | Uint8Array;
+
+export declare interface Column {
+    name: string;
+    /** Raw type string from SQLite (e.g. "VARCHAR(255)", "INTEGER"). */
+    rawType: string;
+    /** Parsed affinity. */
+    affinity: ColumnAffinity;
+    nullable: boolean;
+    defaultValue: string | null;
+    /**
+     * Position in the primary key (1-based), or `null` if the column is not
+     * part of the primary key.
+     */
+    primaryKeyPosition: number | null;
+}
+
+/** SQLite type affinity, parsed from the raw column type string. */
+export declare type ColumnAffinity = "text" | "numeric" | "integer" | "real" | "blob";
+
+export declare interface ColumnConfig {
+    display?: string;
+    options?: Record<string, unknown>;
+    label?: string;
+    hidden?: boolean;
+    /** Force-render on the create form even when Tapemark would hide it
+     *  (e.g. auto-generated INTEGER primary keys). Default `false`. */
+    showOnCreate?: boolean;
+}
+
+/**
+ * Reads and writes per-table display configuration from _tapemark_table_config.
+ * Caches in memory; invalidates on write.
+ */
+export declare class ConfigStore {
+    private db;
+    private cache;
+    constructor(db: Database);
+    getTableConfig(tableName: string): Promise<TableConfig>;
+    setTableConfig(tableName: string, config: TableConfig): Promise<void>;
+    /** Get config for a specific column, with defaults. */
+    getColumnConfig(tableConfig: TableConfig, columnName: string): ColumnConfig;
+    /** Clear the entire cache (e.g. after migration). */
+    invalidate(): void;
+}
+
+/** "enforce" enables FK checks and HTML required attributes. "relaxed" disables both. */
+export declare type ConstraintMode = "enforce" | "relaxed";
+
+export declare function createDisplayTypeRegistry(custom?: Record<string, DisplayType>): Map<string, DisplayType>;
+
+export declare function createTapemark(options: TapemarkOptions): TapemarkCore;
+
+export declare function createTapemark(options: TapemarkBaseOptions): TapemarkCore;
+
+export declare interface Crumb {
+    label: string;
+    href?: string;
+}
+
+/**
+ * Minimal database interface that both D1 and native SQLite can implement.
+ * Adapters wrap the underlying driver to match this shape.
+ */
+export declare interface Database {
+    prepare(query: string): PreparedStatement;
+}
+
+export declare interface DatabaseListItem {
+    name: string;
+    path: string;
+}
+
+export declare function decodePk(primaryKey: string[], encoded: string): Record<string, string>;
+
+export declare const defaultTheme: ThemeName;
+
+export declare interface DisplayType {
+    name: string;
+    description: string;
+    /** JSON Schema describing the configurable options. */
+    schema: OptionSchema;
+    /** Server-side: render a cell value to an HTML string. */
+    render: (value: unknown, options: Record<string, unknown>) => string;
+    /** Server-side: render the form input for editing. */
+    renderInput?: (column: Column, value: unknown, options: Record<string, unknown>) => string;
+    /**
+     * Tag name of a web component that progressively enhances the input.
+     * The component receives the rendered input as its child.
+     */
+    editorComponent?: string;
+}
+
+export declare function encodePk(primaryKey: string[], row: Record<string, unknown>): string;
+
+/** Capability host for fire-and-forget work: `waitUntil(promise)` keeps a
+ *  Promise alive past the response. Available on edge runtimes that share
+ *  this idiom — Cloudflare Workers (`c.executionCtx`), Vercel
+ *  (`@vercel/functions`'s `waitUntil`), and others. Undefined on runtimes
+ *  without the concept (Node, Bun standalone), where hooks just fall back
+ *  to plain async invocations. */
+export declare interface ExecutionContextLike {
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+export declare interface ForeignKey {
+    /** Local column names, ordered by position in the constraint. */
+    columns: string[];
+    referencedTable: string;
+    referencedColumns: string[];
+    onUpdate: string;
+    onDelete: string;
+}
+
+/** Context passed to user-defined hooks and action handlers. `env` is
+ *  `unknown` because the adapter's binding shape isn't known to core —
+ *  cast at the call site (`ctx.env as MyEnv`) for typed access. */
+export declare interface HookContext {
+    db: Database;
+    /** Framework env (e.g. Hono's `c.env`); undefined when not adapter-bound. */
+    env?: unknown;
+    /** Run `work` in the background when the runtime supports it
+     *  (Workers/Vercel/etc.); otherwise await it inline. Always `await` the
+     *  return value — it resolves immediately in background mode and after
+     *  `work` settles in sync mode. Errors are surfaced as flash warnings in
+     *  sync mode but only logged by the runtime in background mode. */
+    background: (work: Promise<unknown>) => Promise<void>;
+    request: TapemarkRequest;
+}
+
+/** True for sole-INTEGER-PK columns on rowid tables — SQLite aliases them
+ *  to rowid and fills them in on INSERT, so admin UIs typically hide them
+ *  on create. `WITHOUT ROWID` tables disable the aliasing, so the column
+ *  is a regular integer PK that the user must supply. */
+export declare function isAutoGeneratedPk(col: Column, primaryKey: string[], hasRowid: boolean): boolean;
+
+export declare function isInternalTable(name: string): boolean;
+
+export declare class NameValidationError extends NotFoundError {
+    readonly kind: "table" | "column";
+    readonly invalidName: string;
+    constructor(kind: "table" | "column", invalidName: string);
+}
+
+export declare class NotFoundError extends TapemarkError {
+    constructor(message: string, detail?: string);
+}
+
+/** JSON Schema subset used for display type option definitions. */
+export declare interface OptionSchema {
+    type: "object";
+    properties: Record<string, {
+        type: "string" | "number" | "boolean";
+        default?: unknown;
+        description?: string;
+        enum?: unknown[];
+    }>;
+}
+
+export declare function parseAffinity(rawType: string): ColumnAffinity;
+
+export declare function pickLabelColumn(table: Awaited<ReturnType<SchemaIntrospector["getTable"]>>): string | null;
+
+export declare interface PreparedStatement {
+    bind(...values: unknown[]): PreparedStatement;
+    /** Return all rows from any row-returning statement — including
+     *  `SELECT`, `INSERT … RETURNING`, `UPDATE … RETURNING`, `DELETE … RETURNING`. */
+    all<T = Record<string, unknown>>(): Promise<T[]>;
+    /** Return the first row from any row-returning statement (see `all`).
+     *  Core uses this on `INSERT … RETURNING *` to recover auto-generated
+     *  values, so adapters must support it on writes, not only on SELECTs. */
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    /** Execute a statement that returns no rows. */
+    run(): Promise<void>;
+}
+
+export declare function renderDatabaseListPage(databases: DatabaseListItem[]): string;
+
+export declare function renderPage(node: Child): string;
+
+export declare interface RequestOverrides {
+    /** Pre-resolved database for this request (bypasses options.db). */
+    db?: Database;
+    /** Framework env forwarded to hook/action handlers (e.g. Hono's `c.env`). */
+    env?: unknown;
+    /** Background-task host forwarded from the adapter (Workers' `executionCtx`,
+     *  Vercel's `waitUntil`, etc.). Undefined on runtimes without the concept. */
+    executionContext?: ExecutionContextLike;
+}
+
+/** A route handler is a pure async function. */
+export declare type RouteHandler = (req: TapemarkRequest, ctx: TapemarkContext) => Promise<TapemarkResponse>;
+
+/** A user-triggered named operation on a row, rendered as a button. */
+export declare interface RowAction {
+    /** Label shown on the button. */
+    label: string;
+    /** Handler invoked when the button is clicked. */
+    handler: (pkValues: Record<string, string>, ctx: HookContext) => Promise<ActionResult> | ActionResult;
+    /** Where to render this action button. Defaults: `detail: true`, `list: false`.
+     *  Invocations from the list view redirect back to the list. */
+    display?: {
+        detail?: boolean;
+        list?: boolean;
+    };
+    /** UI-only predicate hiding the button when it doesn't apply to this row.
+     *  Not enforced server-side; thrown errors are treated as "not visible". */
+    visible?: (row: Record<string, CellValue>) => boolean;
+}
+
+export declare interface RowData {
+    values: Map<string, CellValue>;
+    primaryKey: Map<string, CellValue>;
+}
+
+export declare interface RowResult {
+    columns: Column[];
+    rows: Record<string, CellValue>[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+
+export declare interface Schema {
+    tables: Table[];
+    /** SHA-256 hash of the sorted CREATE TABLE statements. */
+    hash: string;
+}
+
+export declare class SchemaIntrospector {
+    private db;
+    constructor(db: Database);
+    /** All user-facing table and view names (excludes internal tables). */
+    getTableNames(): Promise<string[]>;
+    /** All user-facing tables and views with their kind. */
+    getTableEntries(): Promise<{
+        name: string;
+        kind: "table" | "view";
+    }[]>;
+    /** Validate that a table or view name exists and is safe to use in SQL. */
+    assertTable(name: string): Promise<void>;
+    /** Validate that a column belongs to the given table. */
+    assertColumn(table: string, column: string): Promise<void>;
+    /** Foreign keys for a table (views have none). */
+    getForeignKeys(name: string): Promise<ForeignKey[]>;
+    /** Full column and PK info for a single table or view. */
+    getTable(name: string): Promise<Table>;
+    /** All user-facing tables with column info and row counts. */
+    getTables(): Promise<Table[]>;
+    /**
+     * Full schema snapshot including a hash for sync compatibility.
+     * The hash is computed from the sorted CREATE TABLE statements.
+     */
+    getSchema(): Promise<Schema>;
+}
+
+export declare interface Table {
+    name: string;
+    /** Whether this is a table or a view. */
+    kind: "table" | "view";
+    /** Whether the table has an implicit rowid column. False for views and WITHOUT ROWID tables. */
+    hasRowid: boolean;
+    columns: Column[];
+    /** Ordered list of primary key column names. */
+    primaryKey: string[];
+    foreignKeys: ForeignKey[];
+    rowCount: number;
+}
+
+export declare interface TableConfig {
+    columns?: Record<string, ColumnConfig>;
+    /** Render order for columns. Listed names render first in the given order;
+     *  unlisted columns trail in schema order. Names that no longer match a
+     *  column are silently ignored — Tapemark does not track schema renames. */
+    order?: string[];
+}
+
+/** Row-level lifecycle hooks. Only fire on writes that go through Tapemark. */
+export declare interface TableHooks {
+    /** After a row has been inserted. Receives the full inserted row. */
+    afterInsert?: (row: Record<string, CellValue>, ctx: HookContext) => Promise<void> | void;
+    /** After a row has been updated. Receives the PK and the submitted patch. */
+    afterUpdate?: (pkValues: Record<string, string>, patch: Record<string, string>, ctx: HookContext) => Promise<void> | void;
+    /** After a row has been deleted. Receives the PK of the deleted row. */
+    afterDelete?: (pkValues: Record<string, string>, ctx: HookContext) => Promise<void> | void;
+}
+
+export declare interface TableOptions {
+    readonly?: boolean;
+    hidden?: boolean;
+    hooks?: TableHooks;
+    actions?: Record<string, RowAction>;
+}
+
+export declare class TableRepository {
+    private db;
+    private schema;
+    constructor(db: Database);
+    /** Paginated row listing. */
+    getRows(tableName: string, page?: number, pageSize?: number): Promise<RowResult>;
+    /** Single row by primary key values. */
+    getRow(tableName: string, pkValues: Record<string, string>): Promise<Record<string, CellValue>>;
+    /** Insert a row. Returns it via `RETURNING *` so callers and `afterInsert`
+     *  hooks see auto-generated values regardless of PK affinity. Empty-string
+     *  values are skipped (lets columns fall through to their DEFAULT). */
+    insertRow(tableName: string, data: Record<string, string>): Promise<Record<string, CellValue>>;
+    /** Update a row. PK columns in data are ignored. */
+    updateRow(tableName: string, pkValues: Record<string, string>, data: Record<string, string>): Promise<void>;
+    /** Delete a single row by primary key. */
+    deleteRow(tableName: string, pkValues: Record<string, string>): Promise<void>;
+    /** Delete multiple rows by encoded PK strings. Each delete is a separate
+     *  statement rather than one transaction, so on D1 this is N round-trips and
+     *  a mid-way failure leaves the already-deleted rows committed. */
+    bulkDelete(tableName: string, encodedPks: string[]): Promise<number>;
+}
+
+/**
+ * Base configuration shared by direct users and adapters.
+ * Adapters extend this to add framework-specific fields (like a
+ * context-aware `db` accessor) while `createTapemark` accepts it
+ * directly when the database is provided per-request via overrides.
+ */
+export declare interface TapemarkBaseOptions {
+    /**
+     * Authorization callback. Return `true` to allow, `false` for the default
+     * 403, or a `TapemarkResponse` to override the denial (e.g. a redirect).
+     * If omitted, the panel is unprotected.
+     */
+    authorize?: (req: TapemarkRequest) => Promise<boolean | TapemarkResponse>;
+    /** URL prefix for generating internal links (e.g. "/admin"). */
+    prefix?: string;
+    /** Custom display type definitions. */
+    displayTypes?: Record<string, DisplayType>;
+    /** Per-table overrides. */
+    tables?: Record<string, TableOptions>;
+    /** Additional client-side scripts to load. */
+    scripts?: string[];
+    /** URL to link back to the host site. */
+    siteUrl?: string;
+    /** Label for the site link (e.g. "jvelo.at"). Defaults to "site". */
+    siteName?: string;
+    /** Display name shown in the top-left of the bar. Defaults to "tapemark". */
+    name?: string;
+    /**
+     * Brand mark (emoji or short string) rendered before `name` and used as favicon.
+     * Defaults to "🎞️" when `name` is not set, and to `false` when `name` is customized —
+     * i.e. integrators who rebrand don't get tapemark's mark by accident. Pass a string
+     * to override, or `false` to hide explicitly.
+     */
+    symbol?: string | false;
+    /** Global read-only mode — disables all writes and deletes. */
+    readonly?: boolean;
+    /** Set to false to skip bundled fonts (when the host app already serves them). Defaults to true. */
+    bundleFonts?: boolean;
+    /** Theme name. Defaults to "hubot". */
+    theme?: ThemeName;
+    /** Constraint enforcement mode. Defaults to "enforce". */
+    constraints?: ConstraintMode;
+}
+
+/**
+ * Context passed to route handlers. Built once per request from
+ * resolved options. Handlers never touch raw options.
+ */
+export declare interface TapemarkContext {
+    db: Database;
+    prefix: string;
+    siteUrl?: string;
+    siteName: string;
+    name: string;
+    symbol: string | false;
+    readonly: boolean;
+    constraints: ConstraintMode;
+    theme: ThemeName;
+    bundleFonts: boolean;
+    displayTypes: Map<string, DisplayType>;
+    tableOptions: Map<string, TableOptions>;
+    scripts: string[];
+    /** Framework env forwarded from the adapter; passed through to hook/action handlers. */
+    env?: unknown;
+    /** Framework execution context forwarded from the adapter. */
+    executionContext?: ExecutionContextLike;
+}
+
+export declare interface TapemarkCore {
+    /** Handle an incoming request. */
+    handle(req: TapemarkRequest, overrides?: RequestOverrides): Promise<TapemarkResponse>;
+    /** Register a route. Used internally and by adapters for asset routes. */
+    addRoute(method: "GET" | "POST", pattern: string, handler: RouteHandler): void;
+}
+
+/**
+ * Base error class for all tapemark errors.
+ * Carries an HTTP status code and optional detail for logging.
+ */
+export declare class TapemarkError extends Error {
+    readonly status: number;
+    readonly detail?: string | undefined;
+    constructor(status: number, message: string, detail?: string | undefined);
+}
+
+export declare function TapemarkLayout({ title, prefix, name, symbol, siteUrl, siteName, crumbs, scripts, children, }: TapemarkLayoutProps): JSX.Element;
+
+declare interface TapemarkLayoutProps {
+    title: string;
+    prefix: string;
+    name: string;
+    symbol: string | false;
+    siteUrl?: string;
+    siteName?: string;
+    crumbs?: Crumb[];
+    scripts?: string[];
+    children?: Child;
+}
+
+/**
+ * Manages tapemark's own tables (_tapemark_meta, _tapemark_table_config).
+ * Auto-creates on first use, applies pending migrations on schema upgrades.
+ */
+export declare class TapemarkMigrator {
+    private db;
+    private readonly readonlyMode;
+    private readonly constraints;
+    private initialized;
+    constructor(db: Database, readonlyMode?: boolean, constraints?: ConstraintMode);
+    /** Ensure tapemark tables exist and are up to date. Idempotent. */
+    ensureReady(): Promise<void>;
+    /** Reset initialized flag (useful after config writes that may change state). */
+    resetInitialized(): void;
+    private tableExists;
+    private createInitialSchema;
+    private getSchemaVersion;
+    private applyMigrations;
+    private updateAppSchemaHash;
+}
+
+/** Full options for direct usage — `db` is required. */
+export declare interface TapemarkOptions extends TapemarkBaseOptions {
+    /** Database instance or factory. */
+    db: Database | (() => Database);
+}
+
+export declare interface TapemarkRequest {
+    method: string;
+    /** Path relative to the mount point (e.g. "/users", "/users/42"). */
+    path: string;
+    /** Route parameters extracted from path patterns (e.g. { table: "users", pk: "42" }). */
+    params: Record<string, string>;
+    /** URL query string parameters. */
+    query: Record<string, string>;
+    body?: Record<string, string | string[]>;
+}
+
+export declare interface TapemarkResponse {
+    status: number;
+    headers: Record<string, string>;
+    html?: string;
+    redirect?: string;
+}
+
+export declare interface ThemeDefinition {
+    name: ThemeName;
+    label: string;
+    fontFamily: string;
+    /** Monospace companion — used for UUIDs, JSON, code, hashes. */
+    fontFamilyMono: string;
+    /** Key into the font CSS files (e.g. "depart" → fonts-depart.css). */
+    fontFile: string;
+    /** Base font size for the UI. Table cells scale from this via em units. */
+    fontSizeBase: string;
+    /** Background color. */
+    bg: string;
+    /** Primary text color. */
+    text: string;
+    /** Border / divider color. */
+    border: string;
+    /** Accent color for links, focus, primary actions. */
+    accent: string;
+    /** Text color that reads well on top of the accent color. */
+    accentText: string;
+}
+
+export declare type ThemeName = "hubot" | "plex" | "depart";
+
+export declare const themes: Record<ThemeName, ThemeDefinition>;
+
+export declare class ValidationError extends TapemarkError {
+    constructor(message: string, detail?: string);
+}
+
+export { }