fql-toolkit/dist/FormContext.d.ts

Fql Toolkit

import type FQLHTTPClient from './client.js';
import type { FQLConditionOperator, FQLLiteral, FQLRecord, FQLResult } from './types.js';
/**
 * A chainable query builder for case (record) operations on a specific form.
 * Returned by `client.form('name').labels()` or `.with()`.
 *
 * @example
 * await client.form('customers').labels('name', 'email').with('age', '>', 18).get();
 * await client.form('customers').with('name', '=', 'John').remove();
 * await client.form('customers').with('name', '=', 'John').modify({ name: 'Jane', email: 'jane@example.com', age: 31 });
 */
declare class FormQuery {
    private readonly _formName;
    private readonly _http;
    private _fields;
    private _conditions;
    constructor(formName: string, httpClient: FQLHTTPClient);
    /**
     * Specifies which fields to return.
     * May be called multiple times; fields accumulate.
     */
    labels(...fields: string[]): this;
    /**
     * Adds a filter condition.
     * Multiple calls are combined with AND.
     *
     * @param field    - Field path, e.g. `'age'` or `'owner.name'`
     * @param operator - One of: `=` `!=` `<>` `<` `>` `<=` `>=`
     * @param value    - Value to compare against
     */
    with(field: string, operator: FQLConditionOperator, value: FQLLiteral): this;
    private _condition;
    /** Executes the query and returns matching records. */
    get<T = unknown[]>(): Promise<FQLResult<T>>;
    /**
     * Modifies all records matching the current conditions.
     *
     * Internally this method:
     *   1. Fetches matching records to obtain their `fql_token`(s).
     *   2. Calls `modify case` for each record.
     *
     * ⚠️  Values must be provided in the same order as the form's field definitions.
     *     Include ALL fields, not just the ones changing.
     *
     * @param newValues - `{ fieldName: newValue, ... }` in form-field order
     */
    modify<T = unknown[]>(newValues?: FQLRecord): Promise<FQLResult<T>>;
    /**
     * Removes all records matching the current conditions.
     * At least one `.with()` condition is required.
     *
     * Internally this method:
     *   1. Fetches matching records to obtain their `fql_token`.
     *   2. Calls `remove case` for the matched record using its token.
     */
    remove<T = unknown[]>(): Promise<FQLResult<T>>;
}
/**
 * Entry point for case (record) operations on a single form.
 * Accessed via `client.form('formName')`.
 *
 * @example
 * await client.form('customers').create({ name: 'John', email: 'john@example.com', age: 30 });
 * await client.form('customers').labels('name', 'email').with('age', '>', 18).get();
 * await client.form('customers').with('name', '=', 'John').remove();
 * await client.form('customers').with('name', '=', 'John').modify({ name: 'Jane', email: 'jane@example.com', age: 31 });
 */
export default class FormContext {
    private readonly _formName;
    private readonly _http;
    constructor(formName: string, httpClient: FQLHTTPClient);
    /**
     * Inserts a new record.
     * Values are taken from the object in insertion order and must match
     * the form's field definition order.
     */
    create<T = unknown[]>(data?: FQLRecord): Promise<FQLResult<T>>;
    /**
     * Fetches all records from the form without any conditions or label filters.
     *
     * @example
     * await client.form('Boards').get();
     */
    get<T = unknown[]>(): Promise<FQLResult<T>>;
    /**
     * Starts a query and specifies which fields to return.
     * @returns {FormQuery}
     */
    labels(...fields: string[]): FormQuery;
    /**
     * Starts a query with a filter condition.
     * @returns {FormQuery}
     */
    with(field: string, operator: FQLConditionOperator, value: FQLLiteral): FormQuery;
}
export {};
//# sourceMappingURL=FormContext.d.ts.map