@powerdata/pd4 0.1.0

package/dist/react/index.d.cts

@@ -0,0 +1,198 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** PD4 column info from table details */
+interface ColumnInfo {
+    name: string;
+    dtype: string;
+}
+/** PD4 table info returned by GET /v1/tables/:name */
+interface TableInfo {
+    name: string;
+    columns: ColumnInfo[];
+    row_count: number;
+}
+/** A column-value pair in PD4's row format */
+interface ColumnValue {
+    column: string;
+    value: string | number | boolean | null;
+}
+/** A row as returned by PD4 */
+interface PD4Row {
+    key: number;
+    values: ColumnValue[];
+}
+/** Flat row for display: column name -> value, plus _pk */
+type Row = Record<string, string | number | boolean | null>;
+/** SSE connection status */
+type ConnectionStatus = 'connecting' | 'connected' | 'error';
+/** Callback for insert events: (keys, rows) */
+type InsertHandler = (keys: number[], rows: Row[]) => void;
+/** Callback for update events: (keys, newValues, oldValues) */
+type UpdateHandler = (keys: number[], newValues: Row[], oldValues: Row[]) => void;
+/** Callback for delete events: (keys) */
+type DeleteHandler = (keys: number[]) => void;
+/** Callback for status changes */
+type StatusHandler = (status: ConnectionStatus) => void;
+/** Options for fetch */
+interface FetchOptions {
+    offset?: number;
+    limit?: number;
+}
+/** Result from fetch */
+interface FetchResult {
+    rows: Row[];
+    total: number;
+}
+/** Result from insert */
+interface InsertResult {
+    keys: number[];
+    count: number;
+}
+/** Constructor options for PD4Client */
+interface PD4ClientOptions {
+    /**
+     * Custom EventSource constructor for environments without a global EventSource
+     * (e.g. Node.js). Pass the `EventSource` class from the `eventsource` npm package.
+     */
+    EventSource?: new (url: string) => EventSource;
+}
+
+/**
+ * A buffered view wrapping a PD4 table.
+ * Changes are accumulated locally and only become visible
+ * to other clients after commit().
+ */
+declare class PD4Buffer {
+    private client;
+    readonly handle: string;
+    readonly table: string;
+    constructor(client: PD4Client, handle: string, table: string);
+    /** Update a row within the buffer (not visible to others until commit). */
+    update(key: number, values: Row): Promise<void>;
+    /** Fetch rows from the buffer (sees uncommitted changes). */
+    fetch(offset?: number, limit?: number): Promise<FetchResult>;
+    /** Commit all buffered writes atomically. Fires SSE events. */
+    commit(): Promise<void>;
+    /** Rollback all buffered writes (discard pending changes). */
+    rollback(): Promise<void>;
+    private _request;
+}
+
+declare class PD4Client {
+    readonly url: string;
+    readonly db: string;
+    private EventSourceCtor;
+    private eventSource;
+    private handlers;
+    private statusHandlers;
+    private _status;
+    constructor(url: string, db: string, options?: PD4ClientOptions);
+    private get v1();
+    private get api();
+    private request;
+    /** Check if PD4 is reachable */
+    ping(): Promise<boolean>;
+    /** Ensure the database is open */
+    ensureDatabase(): Promise<void>;
+    /** List all table names */
+    listTables(): Promise<string[]>;
+    /** Get table info */
+    getTable(name: string): Promise<TableInfo>;
+    /** Create a table (with auto_pk) */
+    createTable(name: string): Promise<void>;
+    /** Drop a table */
+    dropTable(name: string): Promise<void>;
+    /** Add a column to a table */
+    addColumn(table: string, name: string, dtype: string): Promise<void>;
+    /** Insert one or more rows (flat objects). Returns keys and count. */
+    insert(table: string, rows: Row | Row[]): Promise<InsertResult>;
+    /** Update a single row by key with a flat object of changed columns. */
+    update(table: string, key: number, values: Row): Promise<void>;
+    /** Delete rows by keys. */
+    delete(table: string, keys: number | number[]): Promise<void>;
+    /** Fetch rows from a table/view. Returns flat Row objects. */
+    fetch(table: string, opts?: FetchOptions): Promise<FetchResult>;
+    /** Insert rows in columnar format (low-level). */
+    insertColumnar(table: string, columns: string[], rows: (string | number | boolean | null)[][]): Promise<InsertResult>;
+    /** Update a row by key with column-value pairs (low-level). */
+    updateRaw(table: string, key: number, values: {
+        column: string;
+        value: string | number | boolean | null;
+    }[]): Promise<void>;
+    /** Fetch rows in PD4 wire format (low-level). */
+    fetchRaw(table: string, offset?: number, limit?: number): Promise<{
+        rows: PD4Row[];
+        total: number;
+    }>;
+    /** Create a buffered view wrapping a table. */
+    buffer(table: string): Promise<PD4Buffer>;
+    /** Get current SSE connection status. */
+    get status(): ConnectionStatus;
+    /** Connect to the SSE event stream. Called automatically on first on(). */
+    connect(): void;
+    /** Disconnect from the SSE event stream. */
+    disconnect(): void;
+    /**
+     * Subscribe to SSE events for a table.
+     * Auto-connects on first call. Returns an unsubscribe function.
+     */
+    on(table: string, event: 'insert', handler: InsertHandler): () => void;
+    on(table: string, event: 'update', handler: UpdateHandler): () => void;
+    on(table: string, event: 'delete', handler: DeleteHandler): () => void;
+    /** Subscribe to connection status changes. Returns an unsubscribe function. */
+    onStatus(handler: StatusHandler): () => void;
+    private _setStatus;
+    private _dispatch;
+}
+
+interface PD4ProviderProps {
+    url: string;
+    db: string;
+    children: React.ReactNode;
+}
+declare function PD4Provider({ url, db, children }: PD4ProviderProps): react_jsx_runtime.JSX.Element;
+declare function usePD4(): PD4Client;
+
+/**
+ * Subscribe to SSE events for a table. Auto-cleans up on unmount.
+ *
+ * Usage:
+ *   usePD4Subscribe('metrics', 'insert', (keys, rows) => { ... })
+ *   usePD4Subscribe('metrics', 'update', (keys, newVals, oldVals) => { ... })
+ *   usePD4Subscribe('metrics', 'delete', (keys) => { ... })
+ */
+declare function usePD4Subscribe(table: string, event: 'insert', handler: InsertHandler): void;
+declare function usePD4Subscribe(table: string, event: 'update', handler: UpdateHandler): void;
+declare function usePD4Subscribe(table: string, event: 'delete', handler: DeleteHandler): void;
+
+interface UsePD4TableOptions {
+    limit?: number;
+    deleteDelay?: number;
+}
+interface UsePD4TableResult {
+    rows: Row[];
+    total: number;
+    columns: ColumnInfo[];
+    status: ConnectionStatus;
+    highlights: Record<number, string>;
+}
+/**
+ * Full table state management hook.
+ * Handles: initial fetch, SSE subscriptions for insert/update/delete,
+ * row state management, highlight tracking, and buffer-commit edge cases.
+ */
+declare function usePD4Table(table: string, opts?: UsePD4TableOptions): UsePD4TableResult;
+
+interface UsePD4QueryResult {
+    rows: Row[];
+    total: number;
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+/**
+ * One-shot query hook. Fetches rows from a table once (or on refetch).
+ */
+declare function usePD4Query(table: string, offset?: number, limit?: number): UsePD4QueryResult;
+
+export { PD4Provider, type PD4ProviderProps, type UsePD4QueryResult, type UsePD4TableOptions, type UsePD4TableResult, usePD4, usePD4Query, usePD4Subscribe, usePD4Table };

package/dist/react/index.d.ts

@@ -0,0 +1,198 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** PD4 column info from table details */
+interface ColumnInfo {
+    name: string;
+    dtype: string;
+}
+/** PD4 table info returned by GET /v1/tables/:name */
+interface TableInfo {
+    name: string;
+    columns: ColumnInfo[];
+    row_count: number;
+}
+/** A column-value pair in PD4's row format */
+interface ColumnValue {
+    column: string;
+    value: string | number | boolean | null;
+}
+/** A row as returned by PD4 */
+interface PD4Row {
+    key: number;
+    values: ColumnValue[];
+}
+/** Flat row for display: column name -> value, plus _pk */
+type Row = Record<string, string | number | boolean | null>;
+/** SSE connection status */
+type ConnectionStatus = 'connecting' | 'connected' | 'error';
+/** Callback for insert events: (keys, rows) */
+type InsertHandler = (keys: number[], rows: Row[]) => void;
+/** Callback for update events: (keys, newValues, oldValues) */
+type UpdateHandler = (keys: number[], newValues: Row[], oldValues: Row[]) => void;
+/** Callback for delete events: (keys) */
+type DeleteHandler = (keys: number[]) => void;
+/** Callback for status changes */
+type StatusHandler = (status: ConnectionStatus) => void;
+/** Options for fetch */
+interface FetchOptions {
+    offset?: number;
+    limit?: number;
+}
+/** Result from fetch */
+interface FetchResult {
+    rows: Row[];
+    total: number;
+}
+/** Result from insert */
+interface InsertResult {
+    keys: number[];
+    count: number;
+}
+/** Constructor options for PD4Client */
+interface PD4ClientOptions {
+    /**
+     * Custom EventSource constructor for environments without a global EventSource
+     * (e.g. Node.js). Pass the `EventSource` class from the `eventsource` npm package.
+     */
+    EventSource?: new (url: string) => EventSource;
+}
+
+/**
+ * A buffered view wrapping a PD4 table.
+ * Changes are accumulated locally and only become visible
+ * to other clients after commit().
+ */
+declare class PD4Buffer {
+    private client;
+    readonly handle: string;
+    readonly table: string;
+    constructor(client: PD4Client, handle: string, table: string);
+    /** Update a row within the buffer (not visible to others until commit). */
+    update(key: number, values: Row): Promise<void>;
+    /** Fetch rows from the buffer (sees uncommitted changes). */
+    fetch(offset?: number, limit?: number): Promise<FetchResult>;
+    /** Commit all buffered writes atomically. Fires SSE events. */
+    commit(): Promise<void>;
+    /** Rollback all buffered writes (discard pending changes). */
+    rollback(): Promise<void>;
+    private _request;
+}
+
+declare class PD4Client {
+    readonly url: string;
+    readonly db: string;
+    private EventSourceCtor;
+    private eventSource;
+    private handlers;
+    private statusHandlers;
+    private _status;
+    constructor(url: string, db: string, options?: PD4ClientOptions);
+    private get v1();
+    private get api();
+    private request;
+    /** Check if PD4 is reachable */
+    ping(): Promise<boolean>;
+    /** Ensure the database is open */
+    ensureDatabase(): Promise<void>;
+    /** List all table names */
+    listTables(): Promise<string[]>;
+    /** Get table info */
+    getTable(name: string): Promise<TableInfo>;
+    /** Create a table (with auto_pk) */
+    createTable(name: string): Promise<void>;
+    /** Drop a table */
+    dropTable(name: string): Promise<void>;
+    /** Add a column to a table */
+    addColumn(table: string, name: string, dtype: string): Promise<void>;
+    /** Insert one or more rows (flat objects). Returns keys and count. */
+    insert(table: string, rows: Row | Row[]): Promise<InsertResult>;
+    /** Update a single row by key with a flat object of changed columns. */
+    update(table: string, key: number, values: Row): Promise<void>;
+    /** Delete rows by keys. */
+    delete(table: string, keys: number | number[]): Promise<void>;
+    /** Fetch rows from a table/view. Returns flat Row objects. */
+    fetch(table: string, opts?: FetchOptions): Promise<FetchResult>;
+    /** Insert rows in columnar format (low-level). */
+    insertColumnar(table: string, columns: string[], rows: (string | number | boolean | null)[][]): Promise<InsertResult>;
+    /** Update a row by key with column-value pairs (low-level). */
+    updateRaw(table: string, key: number, values: {
+        column: string;
+        value: string | number | boolean | null;
+    }[]): Promise<void>;
+    /** Fetch rows in PD4 wire format (low-level). */
+    fetchRaw(table: string, offset?: number, limit?: number): Promise<{
+        rows: PD4Row[];
+        total: number;
+    }>;
+    /** Create a buffered view wrapping a table. */
+    buffer(table: string): Promise<PD4Buffer>;
+    /** Get current SSE connection status. */
+    get status(): ConnectionStatus;
+    /** Connect to the SSE event stream. Called automatically on first on(). */
+    connect(): void;
+    /** Disconnect from the SSE event stream. */
+    disconnect(): void;
+    /**
+     * Subscribe to SSE events for a table.
+     * Auto-connects on first call. Returns an unsubscribe function.
+     */
+    on(table: string, event: 'insert', handler: InsertHandler): () => void;
+    on(table: string, event: 'update', handler: UpdateHandler): () => void;
+    on(table: string, event: 'delete', handler: DeleteHandler): () => void;
+    /** Subscribe to connection status changes. Returns an unsubscribe function. */
+    onStatus(handler: StatusHandler): () => void;
+    private _setStatus;
+    private _dispatch;
+}
+
+interface PD4ProviderProps {
+    url: string;
+    db: string;
+    children: React.ReactNode;
+}
+declare function PD4Provider({ url, db, children }: PD4ProviderProps): react_jsx_runtime.JSX.Element;
+declare function usePD4(): PD4Client;
+
+/**
+ * Subscribe to SSE events for a table. Auto-cleans up on unmount.
+ *
+ * Usage:
+ *   usePD4Subscribe('metrics', 'insert', (keys, rows) => { ... })
+ *   usePD4Subscribe('metrics', 'update', (keys, newVals, oldVals) => { ... })
+ *   usePD4Subscribe('metrics', 'delete', (keys) => { ... })
+ */
+declare function usePD4Subscribe(table: string, event: 'insert', handler: InsertHandler): void;
+declare function usePD4Subscribe(table: string, event: 'update', handler: UpdateHandler): void;
+declare function usePD4Subscribe(table: string, event: 'delete', handler: DeleteHandler): void;
+
+interface UsePD4TableOptions {
+    limit?: number;
+    deleteDelay?: number;
+}
+interface UsePD4TableResult {
+    rows: Row[];
+    total: number;
+    columns: ColumnInfo[];
+    status: ConnectionStatus;
+    highlights: Record<number, string>;
+}
+/**
+ * Full table state management hook.
+ * Handles: initial fetch, SSE subscriptions for insert/update/delete,
+ * row state management, highlight tracking, and buffer-commit edge cases.
+ */
+declare function usePD4Table(table: string, opts?: UsePD4TableOptions): UsePD4TableResult;
+
+interface UsePD4QueryResult {
+    rows: Row[];
+    total: number;
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+/**
+ * One-shot query hook. Fetches rows from a table once (or on refetch).
+ */
+declare function usePD4Query(table: string, offset?: number, limit?: number): UsePD4QueryResult;
+
+export { PD4Provider, type PD4ProviderProps, type UsePD4QueryResult, type UsePD4TableOptions, type UsePD4TableResult, usePD4, usePD4Query, usePD4Subscribe, usePD4Table };