@reactor-cloud/data 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,310 @@
+import { RequestContext, Result } from '@reactor-cloud/shared';
+
+/**
+ * Generic schema for untyped queries.
+ */
+type GenericSchema = {
+    Tables: Record<string, {
+        Row: Record<string, unknown>;
+        Insert: Record<string, unknown>;
+        Update: Record<string, unknown>;
+    }>;
+    Views: Record<string, {
+        Row: Record<string, unknown>;
+    }>;
+    Functions: Record<string, {
+        Args: Record<string, unknown>;
+        Returns: unknown;
+    }>;
+};
+/**
+ * Count mode for queries.
+ */
+type CountMode = 'exact' | 'planned' | 'estimated';
+/**
+ * Response format options.
+ */
+type ResponseFormat = 'json' | 'csv' | 'geojson';
+/**
+ * Filter operators supported by reactor-data.
+ */
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'is' | 'cs' | 'cd' | 'ov' | 'fts';
+/**
+ * Result modifier for single row queries.
+ */
+type ResultModifier = 'single' | 'maybeSingle';
+/**
+ * Query execution options.
+ */
+interface QueryOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Count mode */
+    count?: CountMode;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Return result as CSV */
+    csv?: boolean;
+    /** Return query execution plan */
+    explain?: boolean | {
+        analyze?: boolean;
+        verbose?: boolean;
+        costs?: boolean;
+        buffers?: boolean;
+    };
+}
+/**
+ * Order options.
+ */
+interface OrderOptions {
+    ascending?: boolean;
+    nullsFirst?: boolean;
+    foreignTable?: string;
+}
+/**
+ * Upsert options.
+ */
+interface UpsertOptions {
+    onConflict?: string;
+    ignoreDuplicates?: boolean;
+    count?: CountMode;
+}
+/**
+ * Query result with optional count.
+ */
+interface QueryResult<T> {
+    data: T;
+    count?: number;
+}
+/**
+ * Full-text search options.
+ */
+interface TextSearchOptions {
+    type?: 'plain' | 'phrase' | 'websearch';
+    config?: string;
+}
+/**
+ * Filter value types.
+ */
+type FilterValue = string | number | boolean | null | (string | number | boolean)[];
+/**
+ * Pending filter to be applied.
+ */
+interface PendingFilter {
+    column: string;
+    operator: FilterOperator;
+    value: FilterValue;
+    negated: boolean;
+}
+/**
+ * Type helper for selecting specific columns.
+ */
+type SelectResult<T, Columns extends string> = Pick<T, Extract<keyof T, Columns>>;
+
+/**
+ * PostgrestFilterBuilder provides methods for building filter queries.
+ */
+declare class PostgrestFilterBuilder<T, ResultType = T[]> {
+    protected table: string;
+    protected ctx: RequestContext;
+    protected selectColumns: string;
+    protected filters: PendingFilter[];
+    protected orderClauses: string[];
+    protected limitValue?: number;
+    protected offsetValue?: number;
+    protected countMode?: CountMode;
+    protected signalValue?: AbortSignal;
+    protected customHeaders: Record<string, string>;
+    protected responseFormat: 'json' | 'csv';
+    protected explainMode?: {
+        analyze?: boolean;
+        verbose?: boolean;
+        costs?: boolean;
+        buffers?: boolean;
+    };
+    protected resultModifier?: 'single' | 'maybeSingle';
+    protected method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    protected body?: unknown;
+    constructor(ctx: RequestContext, table: string);
+    /** Equal to */
+    eq<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Not equal to */
+    neq<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Greater than */
+    gt<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Greater than or equal */
+    gte<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Less than */
+    lt<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Less than or equal */
+    lte<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Pattern match (LIKE) */
+    like<K extends keyof T & string>(column: K, pattern: string): this;
+    /** Case-insensitive pattern match (ILIKE) */
+    ilike<K extends keyof T & string>(column: K, pattern: string): this;
+    /** Is NULL or boolean */
+    is<K extends keyof T & string>(column: K, value: null | boolean): this;
+    /** In list */
+    in<K extends keyof T & string>(column: K, values: T[K][]): this;
+    /** Array contains */
+    contains<K extends keyof T & string>(column: K, values: unknown[]): this;
+    /** Array contained by */
+    containedBy<K extends keyof T & string>(column: K, values: unknown[]): this;
+    /** Array overlaps */
+    overlaps<K extends keyof T & string>(column: K, values: unknown[]): this;
+    /** Full-text search */
+    textSearch<K extends keyof T & string>(column: K, query: string, options?: TextSearchOptions): this;
+    /** Match multiple conditions (shorthand for multiple eq) */
+    match(query: Partial<T>): this;
+    /** Negate a filter */
+    not<K extends keyof T & string>(column: K, operator: FilterOperator, value: FilterValue): this;
+    /** OR condition (raw string format) */
+    or(conditions: string, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Generic filter (escape hatch) */
+    filter<K extends keyof T & string>(column: K, operator: FilterOperator, value: FilterValue): this;
+    /** Order results */
+    order<K extends keyof T & string>(column: K, options?: OrderOptions): this;
+    /** Limit results */
+    limit(count: number, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Offset results (for pagination) */
+    range(from: number, to: number, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Provide an AbortSignal */
+    abortSignal(signal: AbortSignal): this;
+    /** Return CSV instead of JSON */
+    csv(): PostgrestFilterBuilder<T, string>;
+    /** Return query execution plan */
+    explain(options?: {
+        analyze?: boolean;
+        verbose?: boolean;
+        costs?: boolean;
+        buffers?: boolean;
+    }): this;
+    /** Override return type */
+    returns<R>(): PostgrestFilterBuilder<R, R[]>;
+    /** Execute and return exactly one row (throws if not exactly one) */
+    single(): PostgrestFilterBuilder<T, T>;
+    /** Execute and return zero or one row */
+    maybeSingle(): PostgrestFilterBuilder<T, T | null>;
+    protected buildUrl(): string;
+    protected buildHeaders(): Record<string, string>;
+    /** Execute the query */
+    then<TResult1 = Result<ResultType>, TResult2 = never>(onfulfilled?: ((value: Result<ResultType>) => TResult1 | PromiseLike<TResult1>) | null, _onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    protected execute(): Promise<Result<unknown>>;
+    /** Throw on error instead of returning { data, error } */
+    throwOnError(): Promise<ResultType>;
+}
+/**
+ * Builder for SELECT queries with column selection.
+ */
+declare class PostgrestQueryBuilder<T> extends PostgrestFilterBuilder<T> {
+    /** Select specific columns */
+    select<Columns extends string = '*'>(columns?: Columns, options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+    /** Insert row(s) */
+    insert(values: Partial<T> | Partial<T>[], options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+    /** Upsert row(s) */
+    upsert(values: Partial<T> | Partial<T>[], options?: UpsertOptions): PostgrestFilterBuilder<T>;
+    /** Update row(s) */
+    update(values: Partial<T>, options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+    /** Delete row(s) */
+    delete(options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+}
+
+/**
+ * Call a database function via RPC.
+ */
+declare function rpc<Args extends Record<string, unknown>, Returns>(ctx: RequestContext, functionName: string, args: Args, options?: {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}): Promise<Result<Returns>>;
+/**
+ * RPC builder for type-safe function calls.
+ */
+declare class RpcBuilder<Args extends Record<string, unknown>, Returns> {
+    private ctx;
+    private functionName;
+    private args?;
+    private signal?;
+    private customHeaders;
+    constructor(ctx: RequestContext, functionName: string);
+    /** Set function arguments */
+    call(args: Args): this;
+    /** Provide an AbortSignal */
+    abortSignal(signal: AbortSignal): this;
+    /** Set custom headers */
+    headers(headers: Record<string, string>): this;
+    /** Execute the RPC call */
+    then<TResult1 = Result<Returns>, TResult2 = never>(onfulfilled?: ((value: Result<Returns>) => TResult1 | PromiseLike<TResult1>) | null, _onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /** Throw on error */
+    throwOnError(): Promise<Returns>;
+}
+
+/**
+ * Data client for Reactor - PostgREST-style query builder.
+ *
+ * @example
+ * ```ts
+ * const client = new DataClient(ctx);
+ *
+ * // Select with filters
+ * const { data, error } = await client
+ *   .from('posts')
+ *   .select('id, title, author:users(name)')
+ *   .eq('published', true)
+ *   .order('created_at', { ascending: false })
+ *   .limit(10);
+ *
+ * // Insert
+ * const { data } = await client
+ *   .from('posts')
+ *   .insert({ title: 'Hello', body: 'World' })
+ *   .select()
+ *   .single();
+ *
+ * // RPC
+ * const { data } = await client.rpc('search', { query: 'rust' });
+ * ```
+ */
+declare class DataClient<Schema extends GenericSchema = GenericSchema> {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Start a query on a table.
+     *
+     * @param table - The table name
+     * @returns A query builder
+     */
+    from<TableName extends keyof Schema['Tables'] & string>(table: TableName): PostgrestQueryBuilder<Schema['Tables'][TableName]['Row']>;
+    /**
+     * Call a database function via RPC.
+     *
+     * @param functionName - The function name
+     * @param args - Function arguments
+     * @returns RPC builder
+     */
+    rpc<FunctionName extends keyof Schema['Functions'] & string, Args extends Schema['Functions'][FunctionName]['Args'], Returns = Schema['Functions'][FunctionName]['Returns']>(functionName: FunctionName, args?: Args): RpcBuilder<Args, Returns>;
+    /**
+     * Access a schema (for multi-schema support).
+     * Currently returns self as we only support public schema.
+     */
+    schema(_name: string): DataClient<Schema>;
+}
+/**
+ * Create a data client with typed schema.
+ */
+declare function createDataClient<Schema extends GenericSchema = GenericSchema>(ctx: RequestContext): DataClient<Schema>;
+
+export { type CountMode, DataClient, type FilterOperator, type FilterValue, type GenericSchema, type OrderOptions, type PendingFilter, PostgrestFilterBuilder, PostgrestQueryBuilder, type QueryOptions, type QueryResult, type ResponseFormat, type ResultModifier, RpcBuilder, type SelectResult, type TextSearchOptions, type UpsertOptions, createDataClient, rpc };

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+import { RequestContext, Result } from '@reactor-cloud/shared';
+
+/**
+ * Generic schema for untyped queries.
+ */
+type GenericSchema = {
+    Tables: Record<string, {
+        Row: Record<string, unknown>;
+        Insert: Record<string, unknown>;
+        Update: Record<string, unknown>;
+    }>;
+    Views: Record<string, {
+        Row: Record<string, unknown>;
+    }>;
+    Functions: Record<string, {
+        Args: Record<string, unknown>;
+        Returns: unknown;
+    }>;
+};
+/**
+ * Count mode for queries.
+ */
+type CountMode = 'exact' | 'planned' | 'estimated';
+/**
+ * Response format options.
+ */
+type ResponseFormat = 'json' | 'csv' | 'geojson';
+/**
+ * Filter operators supported by reactor-data.
+ */
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'is' | 'cs' | 'cd' | 'ov' | 'fts';
+/**
+ * Result modifier for single row queries.
+ */
+type ResultModifier = 'single' | 'maybeSingle';
+/**
+ * Query execution options.
+ */
+interface QueryOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Count mode */
+    count?: CountMode;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Return result as CSV */
+    csv?: boolean;
+    /** Return query execution plan */
+    explain?: boolean | {
+        analyze?: boolean;
+        verbose?: boolean;
+        costs?: boolean;
+        buffers?: boolean;
+    };
+}
+/**
+ * Order options.
+ */
+interface OrderOptions {
+    ascending?: boolean;
+    nullsFirst?: boolean;
+    foreignTable?: string;
+}
+/**
+ * Upsert options.
+ */
+interface UpsertOptions {
+    onConflict?: string;
+    ignoreDuplicates?: boolean;
+    count?: CountMode;
+}
+/**
+ * Query result with optional count.
+ */
+interface QueryResult<T> {
+    data: T;
+    count?: number;
+}
+/**
+ * Full-text search options.
+ */
+interface TextSearchOptions {
+    type?: 'plain' | 'phrase' | 'websearch';
+    config?: string;
+}
+/**
+ * Filter value types.
+ */
+type FilterValue = string | number | boolean | null | (string | number | boolean)[];
+/**
+ * Pending filter to be applied.
+ */
+interface PendingFilter {
+    column: string;
+    operator: FilterOperator;
+    value: FilterValue;
+    negated: boolean;
+}
+/**
+ * Type helper for selecting specific columns.
+ */
+type SelectResult<T, Columns extends string> = Pick<T, Extract<keyof T, Columns>>;
+
+/**
+ * PostgrestFilterBuilder provides methods for building filter queries.
+ */
+declare class PostgrestFilterBuilder<T, ResultType = T[]> {
+    protected table: string;
+    protected ctx: RequestContext;
+    protected selectColumns: string;
+    protected filters: PendingFilter[];
+    protected orderClauses: string[];
+    protected limitValue?: number;
+    protected offsetValue?: number;
+    protected countMode?: CountMode;
+    protected signalValue?: AbortSignal;
+    protected customHeaders: Record<string, string>;
+    protected responseFormat: 'json' | 'csv';
+    protected explainMode?: {
+        analyze?: boolean;
+        verbose?: boolean;
+        costs?: boolean;
+        buffers?: boolean;
+    };
+    protected resultModifier?: 'single' | 'maybeSingle';
+    protected method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    protected body?: unknown;
+    constructor(ctx: RequestContext, table: string);
+    /** Equal to */
+    eq<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Not equal to */
+    neq<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Greater than */
+    gt<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Greater than or equal */
+    gte<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Less than */
+    lt<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Less than or equal */
+    lte<K extends keyof T & string>(column: K, value: T[K]): this;
+    /** Pattern match (LIKE) */
+    like<K extends keyof T & string>(column: K, pattern: string): this;
+    /** Case-insensitive pattern match (ILIKE) */
+    ilike<K extends keyof T & string>(column: K, pattern: string): this;
+    /** Is NULL or boolean */
+    is<K extends keyof T & string>(column: K, value: null | boolean): this;
+    /** In list */
+    in<K extends keyof T & string>(column: K, values: T[K][]): this;
+    /** Array contains */
+    contains<K extends keyof T & string>(column: K, values: unknown[]): this;
+    /** Array contained by */
+    containedBy<K extends keyof T & string>(column: K, values: unknown[]): this;
+    /** Array overlaps */
+    overlaps<K extends keyof T & string>(column: K, values: unknown[]): this;
+    /** Full-text search */
+    textSearch<K extends keyof T & string>(column: K, query: string, options?: TextSearchOptions): this;
+    /** Match multiple conditions (shorthand for multiple eq) */
+    match(query: Partial<T>): this;
+    /** Negate a filter */
+    not<K extends keyof T & string>(column: K, operator: FilterOperator, value: FilterValue): this;
+    /** OR condition (raw string format) */
+    or(conditions: string, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Generic filter (escape hatch) */
+    filter<K extends keyof T & string>(column: K, operator: FilterOperator, value: FilterValue): this;
+    /** Order results */
+    order<K extends keyof T & string>(column: K, options?: OrderOptions): this;
+    /** Limit results */
+    limit(count: number, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Offset results (for pagination) */
+    range(from: number, to: number, options?: {
+        foreignTable?: string;
+    }): this;
+    /** Provide an AbortSignal */
+    abortSignal(signal: AbortSignal): this;
+    /** Return CSV instead of JSON */
+    csv(): PostgrestFilterBuilder<T, string>;
+    /** Return query execution plan */
+    explain(options?: {
+        analyze?: boolean;
+        verbose?: boolean;
+        costs?: boolean;
+        buffers?: boolean;
+    }): this;
+    /** Override return type */
+    returns<R>(): PostgrestFilterBuilder<R, R[]>;
+    /** Execute and return exactly one row (throws if not exactly one) */
+    single(): PostgrestFilterBuilder<T, T>;
+    /** Execute and return zero or one row */
+    maybeSingle(): PostgrestFilterBuilder<T, T | null>;
+    protected buildUrl(): string;
+    protected buildHeaders(): Record<string, string>;
+    /** Execute the query */
+    then<TResult1 = Result<ResultType>, TResult2 = never>(onfulfilled?: ((value: Result<ResultType>) => TResult1 | PromiseLike<TResult1>) | null, _onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    protected execute(): Promise<Result<unknown>>;
+    /** Throw on error instead of returning { data, error } */
+    throwOnError(): Promise<ResultType>;
+}
+/**
+ * Builder for SELECT queries with column selection.
+ */
+declare class PostgrestQueryBuilder<T> extends PostgrestFilterBuilder<T> {
+    /** Select specific columns */
+    select<Columns extends string = '*'>(columns?: Columns, options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+    /** Insert row(s) */
+    insert(values: Partial<T> | Partial<T>[], options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+    /** Upsert row(s) */
+    upsert(values: Partial<T> | Partial<T>[], options?: UpsertOptions): PostgrestFilterBuilder<T>;
+    /** Update row(s) */
+    update(values: Partial<T>, options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+    /** Delete row(s) */
+    delete(options?: {
+        count?: CountMode;
+    }): PostgrestFilterBuilder<T>;
+}
+
+/**
+ * Call a database function via RPC.
+ */
+declare function rpc<Args extends Record<string, unknown>, Returns>(ctx: RequestContext, functionName: string, args: Args, options?: {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}): Promise<Result<Returns>>;
+/**
+ * RPC builder for type-safe function calls.
+ */
+declare class RpcBuilder<Args extends Record<string, unknown>, Returns> {
+    private ctx;
+    private functionName;
+    private args?;
+    private signal?;
+    private customHeaders;
+    constructor(ctx: RequestContext, functionName: string);
+    /** Set function arguments */
+    call(args: Args): this;
+    /** Provide an AbortSignal */
+    abortSignal(signal: AbortSignal): this;
+    /** Set custom headers */
+    headers(headers: Record<string, string>): this;
+    /** Execute the RPC call */
+    then<TResult1 = Result<Returns>, TResult2 = never>(onfulfilled?: ((value: Result<Returns>) => TResult1 | PromiseLike<TResult1>) | null, _onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /** Throw on error */
+    throwOnError(): Promise<Returns>;
+}
+
+/**
+ * Data client for Reactor - PostgREST-style query builder.
+ *
+ * @example
+ * ```ts
+ * const client = new DataClient(ctx);
+ *
+ * // Select with filters
+ * const { data, error } = await client
+ *   .from('posts')
+ *   .select('id, title, author:users(name)')
+ *   .eq('published', true)
+ *   .order('created_at', { ascending: false })
+ *   .limit(10);
+ *
+ * // Insert
+ * const { data } = await client
+ *   .from('posts')
+ *   .insert({ title: 'Hello', body: 'World' })
+ *   .select()
+ *   .single();
+ *
+ * // RPC
+ * const { data } = await client.rpc('search', { query: 'rust' });
+ * ```
+ */
+declare class DataClient<Schema extends GenericSchema = GenericSchema> {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Start a query on a table.
+     *
+     * @param table - The table name
+     * @returns A query builder
+     */
+    from<TableName extends keyof Schema['Tables'] & string>(table: TableName): PostgrestQueryBuilder<Schema['Tables'][TableName]['Row']>;
+    /**
+     * Call a database function via RPC.
+     *
+     * @param functionName - The function name
+     * @param args - Function arguments
+     * @returns RPC builder
+     */
+    rpc<FunctionName extends keyof Schema['Functions'] & string, Args extends Schema['Functions'][FunctionName]['Args'], Returns = Schema['Functions'][FunctionName]['Returns']>(functionName: FunctionName, args?: Args): RpcBuilder<Args, Returns>;
+    /**
+     * Access a schema (for multi-schema support).
+     * Currently returns self as we only support public schema.
+     */
+    schema(_name: string): DataClient<Schema>;
+}
+/**
+ * Create a data client with typed schema.
+ */
+declare function createDataClient<Schema extends GenericSchema = GenericSchema>(ctx: RequestContext): DataClient<Schema>;
+
+export { type CountMode, DataClient, type FilterOperator, type FilterValue, type GenericSchema, type OrderOptions, type PendingFilter, PostgrestFilterBuilder, PostgrestQueryBuilder, type QueryOptions, type QueryResult, type ResponseFormat, type ResultModifier, RpcBuilder, type SelectResult, type TextSearchOptions, type UpsertOptions, createDataClient, rpc };