prostgles-client/dist/prostgles.d.ts

Reactive client for Postgres

import type { AnyObject, ClientSchema, ClientSyncHandles, DBSchema, DBSchemaTable, EqualityFilter, FullFilter, SQLHandler, SQLResult, SelectParams, SelectReturnType, ServerFunctionHandler, SubscribeParams, SyncTableInfo, TableHandler, UserLike } from "prostgles-types";
import { asName } from "prostgles-types";
import type { Socket } from "socket.io-client";
import { type AuthHandler } from "./getAuthHandler";
import { type ClientFunctionHandler } from "./getMethods";
import { type Subscription } from "./getSubscriptionHandler";
import type { DbTableSync, Sync, SyncDataItem, SyncOne, SyncOneOptions, SyncOptions, SyncedTable } from "./SyncedTable/SyncedTable";
export declare const isClientSide: boolean;
export declare const debug: any;
export * from "./hooks/useEffectDeep";
export * from "./hooks/useProstglesClient";
export { SQLResult, ServerFunctionHandler, asName };
/**
 * Async result type:
 * - data: the expected data
 * - isLoading: true when data is being fetched (initially or on subsequent filter/option changes)
 * - error: any error that occurred
 */
export type AsyncResult<T> = {
    data?: undefined;
    isLoading: true;
    error?: undefined;
} | {
    data: T;
    isLoading: boolean;
    error?: unknown;
};
export type HookOptions = {
    /**
     * Used to prevent the hook from fetching data
     */
    skip?: boolean;
    /**
     * Used to trigger re-fetching
     */
    deps?: any[];
};
export type TableHandlerClientMethods<T extends AnyObject = AnyObject, S extends DBSchema | void = void> = {
    /**
     * Retrieves rows matching the filter and keeps them in sync
     * - use { handlesOnData: true } to get optimistic updates method: $update
     * - any changes to the row using the $update method will be reflected instantly
     *    to all sync subscribers that were initiated with the same syncOptions
     */
    useSync?: <TD extends T>(basicFilter: EqualityFilter<TD>, syncOptions: SyncOptions, hookOptions?: HookOptions) => AsyncResult<SyncDataItem<Required<TD>>[] | undefined>;
    sync?: Sync<T>;
    syncOne?: SyncOne<T>;
    /**
     * Retrieves the first row matching the filter and keeps it in sync
     * - use { handlesOnData: true } to get optimistic updates method: $update
     * - any changes to the row using the $update method will be reflected instantly
     *    to all sync subscribers that were initiated with the same syncOptions
     */
    useSyncOne?: <TD extends T>(basicFilter: EqualityFilter<TD>, syncOptions: SyncOneOptions, hookOptions?: HookOptions) => AsyncResult<SyncDataItem<Required<TD>> | undefined>;
    /**
     * Used internally to setup sync
     */
    _sync?: (filter: EqualityFilter<AnyObject> | undefined, selectParams: {
        select: AnyObject | "*";
    }, triggers: ClientSyncHandles) => Promise<DbTableSync>;
    _syncInfo?: SyncTableInfo;
    getSync?: AnyObject;
    /**
     * Retrieves a list of matching records from the view/table and subscribes to changes
     */
    useSubscribe: <SubParams extends SubscribeParams<T, S>>(filter?: FullFilter<T, S>, options?: SubParams, hookOptions?: HookOptions) => AsyncResult<SelectReturnType<S, SubParams, T, true> | undefined>;
    /**
     * Retrieves a matching record from the view/table and subscribes to changes
     */
    useSubscribeOne: <SubParams extends SubscribeParams<T, S>>(filter?: FullFilter<T, S>, options?: SubParams, hookOptions?: HookOptions) => AsyncResult<SelectReturnType<S, SubParams, T, false> | undefined>;
    /**
     * Retrieves a list of matching records from the view/table
     */
    useFind: <P extends SelectParams<T, S>>(filter?: FullFilter<T, S>, selectParams?: P, hookOptions?: HookOptions) => AsyncResult<SelectReturnType<S, P, T, true> | undefined>;
    /**
     * Retrieves first matching record from the view/table
     */
    useFindOne: <P extends SelectParams<T, S>>(filter?: FullFilter<T, S>, selectParams?: P, hookOptions?: HookOptions) => AsyncResult<SelectReturnType<S, P, T, false> | undefined>;
    /**
     * Returns the total number of rows matching the filter
     */
    useCount: <P extends SelectParams<T, S>>(filter?: FullFilter<T, S>, selectParams?: P, hookOptions?: HookOptions) => AsyncResult<number | undefined>;
    /**
     * Returns result size in bits matching the filter and selectParams
     */
    useSize: <P extends SelectParams<T, S>>(filter?: FullFilter<T, S>, selectParams?: P, hookOptions?: HookOptions) => AsyncResult<string | undefined>;
};
export type TableHandlerClient<T extends AnyObject = AnyObject, S extends DBSchema | void = void> = TableHandler<T, S> & TableHandlerClientMethods<T, S>;
export type DBHandlerClient<Schema = void> = Schema extends DBSchema ? {
    [tov_name in keyof Schema]: TableHandler<Schema[tov_name]["columns"], Schema> & TableHandlerClientMethods<Schema[tov_name]["columns"], Schema>;
} : Record<string, Partial<TableHandler & TableHandlerClientMethods>>;
export type ClientOnReadyParams<DBSchema = void, FunctionHandler extends ClientFunctionHandler = ClientFunctionHandler, U extends UserLike = UserLike> = {
    /**
     * The database handler object.
     * Only allowed tables and table methods are defined
     */
    db: Partial<DBHandlerClient<DBSchema>>;
    sql: SQLHandler | undefined;
    /**
     * Server-side TS function handlers
     * Only allowed methods are defined
     */
    methods: FunctionHandler | undefined;
    methodSchema: ServerFunctionHandler | undefined;
    /**
     * Table schema with column permission details the client has access to
     */
    tableSchema: DBSchemaTable[] | undefined;
    auth: AuthHandler<U>;
    isReconnect: boolean;
    socket: Socket;
};
type SyncDebugEvent = {
    type: "sync";
    tableName: string;
    channelName: string;
    command: keyof ClientSyncHandles;
    data: AnyObject;
};
type DebugEvent = {
    type: "subscriptions";
    command: "reAttachAll.start";
    subscriptions: Map<string, Subscription>;
} | {
    type: "subscriptions";
    command: "reAttachAll.end";
    subscriptions: Map<string, Subscription>;
} | {
    type: "table";
    command: "unsubscribe";
    tableName: string;
    handlers: AnyFunction[];
    /**
     * If defined then the server will be asked to unsubscribe
     */
    unsubChannel?: string;
} | {
    type: "table";
    command: keyof TableHandlerClient;
    tableName: string;
    data: AnyObject;
} | {
    type: "method";
    command: string;
    data: AnyObject;
} | SyncDebugEvent | {
    type: "schemaChanged";
    data: ClientSchema;
    state: "connected" | "disconnected" | "reconnected" | undefined;
} | {
    type: "onReady";
    data: ClientOnReadyParams;
} | {
    type: "onReady.notMounted";
    data: ClientOnReadyParams;
} | {
    type: "onReady.call";
    data: ClientOnReadyParams;
    state: "connected" | "disconnected" | "reconnected" | undefined;
};
export type InitOptions<DBSchema = void, FuncSchema extends ClientFunctionHandler = ClientFunctionHandler, U extends UserLike = UserLike> = {
    /**
     * Prostgles UI host url
     */
    endpoint?: string;
    credentials?: RequestCredentials;
    redirect?: RequestRedirect;
    /**
     * Socket.io client instance
     */
    socket: Socket;
    /**
     * Execute this when requesting user reload (due to session expiring authGuard)
     * Otherwise window will reload
     */
    onReload?: () => void;
    /**
     * Callback called when schema changes.
     * "onReady" will be called after this callback
     */
    onSchemaChange?: () => void;
    /**
     * Callback called when:
     * - the client connects for the first time
     * - the schema changes
     * - the client reconnects
     * - server requests a reload
     */
    onReady: OnReadyCallback<DBSchema, FuncSchema, U>;
    /**
     * Custom handler in case of websocket re-connection.
     * If not provided will fire onReady
     */
    onReconnect?: (socket: any, error?: any) => void;
    /**
     * On disconnect handler.
     * It is recommended to use this callback instead of socket.on("disconnect")
     */
    onDisconnect?: () => void;
    /**
     * Awaited debug callback.
     * Allows greater granularity during debugging.
     */
    onDebug?: (event: DebugEvent) => void | Promise<void>;
};
type OnReadyCallback<DBSchema = void, FuncSchema extends ClientFunctionHandler = ClientFunctionHandler, U extends UserLike = UserLike> = (onReadyParams: ClientOnReadyParams<DBSchema, FuncSchema, U>) => void | Promise<void>;
export type AnyFunction = (...args: any[]) => any;
export type CoreParams = {
    tableName: string;
    command: string;
    param1?: AnyObject;
    param2?: AnyObject;
};
export type onUpdatesParams = {
    data: object[];
    isSynced: boolean;
};
export type SyncInfo = {
    id_fields: string[];
    synced_field: string;
    channelName: string;
};
export declare function prostgles<DBSchema, FuncSchema extends ClientFunctionHandler, U extends UserLike>(initOpts: InitOptions<DBSchema, FuncSchema, U>, syncedTable: typeof SyncedTable | undefined): Promise<unknown>;
//# sourceMappingURL=prostgles.d.ts.map