@proofkit/fmodata
Version:
FileMaker OData API client
150 lines (149 loc) • 11 kB
TypeScript
import { Column } from '../../orm/column.js';
import { FilterExpression, OrderByExpression } from '../../orm/operators.js';
import { ExtractTableName, FMTable, InferSchemaOutputFromFMTable, ValidExpandTarget } from '../../orm/table.js';
import { FMODataLayer } from '../../services.js';
import { ConditionallyWithODataAnnotations, ConditionallyWithSpecialColumns, ExecutableBuilder, ExecuteMethodOptions, ExecuteOptions, NormalizeIncludeSpecialColumns, Result } from '../../types.js';
import { ExpandedRelations } from '../builders/index.js';
import { QueryReturnType, SystemColumnsOption, TypeSafeOrderBy } from './types.js';
export type { ExpandedRelations } from '../builders/index.js';
export type { CountedListResult, QueryReturnType, SystemColumnsOption, TypeSafeOrderBy } from './types.js';
type QueryBuilderHasSelect<Occ extends FMTable<any, any>, Selected> = Selected extends Record<string, Column<any, any, any>> ? true : Selected extends keyof InferSchemaOutputFromFMTable<Occ> ? false : true;
type BaseQueryBuilderReturn<Occ extends FMTable<any, any>, Selected extends keyof InferSchemaOutputFromFMTable<Occ> | Record<string, Column<any, any, ExtractTableName<Occ>>>, SingleMode extends "exact" | "maybe" | false, IsCount extends boolean, Expands extends ExpandedRelations, IncludeCount extends boolean, SystemCols extends SystemColumnsOption | undefined> = QueryReturnType<InferSchemaOutputFromFMTable<Occ>, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>;
type ExecutableQueryBuilderReturn<Occ extends FMTable<any, any>, Selected extends keyof InferSchemaOutputFromFMTable<Occ> | Record<string, Column<any, any, ExtractTableName<Occ>>>, SingleMode extends "exact" | "maybe" | false, IsCount extends boolean, Expands extends ExpandedRelations, IncludeCount extends boolean, SystemCols extends SystemColumnsOption | undefined> = ConditionallyWithODataAnnotations<ConditionallyWithSpecialColumns<BaseQueryBuilderReturn<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>, true, QueryBuilderHasSelect<Occ, Selected>>, true> | ConditionallyWithODataAnnotations<ConditionallyWithSpecialColumns<BaseQueryBuilderReturn<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>, true, QueryBuilderHasSelect<Occ, Selected>>, false> | ConditionallyWithODataAnnotations<ConditionallyWithSpecialColumns<BaseQueryBuilderReturn<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>, false, QueryBuilderHasSelect<Occ, Selected>>, true> | ConditionallyWithODataAnnotations<ConditionallyWithSpecialColumns<BaseQueryBuilderReturn<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>, false, QueryBuilderHasSelect<Occ, Selected>>, false>;
export declare class QueryBuilder<Occ extends FMTable<any, any>, Selected extends keyof InferSchemaOutputFromFMTable<Occ> | Record<string, Column<any, any, ExtractTableName<Occ>>> = keyof InferSchemaOutputFromFMTable<Occ>, SingleMode extends "exact" | "maybe" | false = false, IsCount extends boolean = false, Expands extends ExpandedRelations = {}, IncludeCount extends boolean = false, DatabaseIncludeSpecialColumns extends boolean = false, SystemCols extends SystemColumnsOption | undefined = undefined> implements ExecutableBuilder<ExecutableQueryBuilderReturn<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>> {
private readState;
private readonly occurrence;
private readonly expandBuilder;
private urlBuilder;
private readonly layer;
private readonly config;
private readonly logger;
private get queryOptions();
private set queryOptions(value);
private get expandConfigs();
private set expandConfigs(value);
private get singleMode();
private set singleMode(value);
private get isCountMode();
private set isCountMode(value);
private get includeCountMode();
private set includeCountMode(value);
private get fieldMapping();
private set fieldMapping(value);
private get systemColumns();
private set systemColumns(value);
private get navigation();
private set navigation(value);
constructor(config: {
occurrence: Occ;
layer: FMODataLayer;
});
/**
* Helper to merge database-level useEntityIds and includeSpecialColumns with per-request options
*/
private mergeExecuteOptions;
private patchQueryOptions;
private setFilterExpression;
private setNavigation;
/**
* Creates a new QueryBuilder with modified configuration.
* Used by single(), maybeSingle(), count(), and select() to create new instances.
*/
private cloneWithChanges;
/**
* Select fields using column references, or pass "all" to clear any defaultSelect and fetch all fields.
* Allows renaming fields by using different keys in the object.
* Container fields cannot be selected and will cause a type error.
*
* @example
* db.from(users).list().select({
* name: users.name,
* userEmail: users.email // renamed!
* })
*
* @example
* // Include system columns (ROWID, ROWMODID) when using select()
* db.from(users).list().select(
* { name: users.name },
* { ROWID: true, ROWMODID: true }
* )
*
* @example
* // Override defaultSelect to fetch all fields
* db.from(users).list().select("all")
*
* @param fields - Object mapping output keys to column references (container fields excluded), or "all" to select all fields
* @param systemColumns - Optional object to request system columns (ROWID, ROWMODID)
* @returns QueryBuilder with updated selected fields
*/
select(fields: "all"): QueryBuilder<Occ, keyof InferSchemaOutputFromFMTable<Occ>, SingleMode, IsCount, Expands, IncludeCount, DatabaseIncludeSpecialColumns, undefined>;
select<TSelect extends Record<string, Column<any, any, ExtractTableName<Occ>, false>>, TSystemCols extends SystemColumnsOption = {}>(fields: TSelect, systemColumns?: TSystemCols): QueryBuilder<Occ, TSelect, SingleMode, IsCount, Expands, IncludeCount, DatabaseIncludeSpecialColumns, TSystemCols>;
/**
* Filter results using operator expressions (new ORM-style API).
* Supports eq, gt, lt, and, or, etc. operators with Column references.
* Also supports raw OData filter strings as an escape hatch.
*
* @example
* .where(eq(users.hobby, "reading"))
* .where(and(eq(users.active, true), gt(users.age, 18)))
* .where("status eq 'active'") // Raw OData string escape hatch
*/
where(expression: FilterExpression | string): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, DatabaseIncludeSpecialColumns, SystemCols>;
/**
* Specify the sort order for query results.
*
* @example Single field (ascending by default)
* ```ts
* .orderBy("name")
* .orderBy(users.name) // Column reference
* .orderBy(asc(users.name)) // Explicit ascending
* ```
*
* @example Single field with explicit direction
* ```ts
* .orderBy(["name", "desc"])
* .orderBy([users.name, "desc"]) // Column reference
* .orderBy(desc(users.name)) // Explicit descending
* ```
*
* @example Multiple fields with directions
* ```ts
* .orderBy([["name", "asc"], ["createdAt", "desc"]])
* .orderBy([[users.name, "asc"], [users.createdAt, "desc"]]) // Column references
* .orderBy(users.name, desc(users.age)) // Variadic with helpers
* ```
*/
orderBy(...orderByArgs: [
TypeSafeOrderBy<InferSchemaOutputFromFMTable<Occ>> | Column<any, any, ExtractTableName<Occ>> | OrderByExpression<ExtractTableName<Occ>>
] | [
Column<any, any, ExtractTableName<Occ>>,
...Array<Column<any, any, ExtractTableName<Occ>> | OrderByExpression<ExtractTableName<Occ>>>
]): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, DatabaseIncludeSpecialColumns, SystemCols>;
top(count: number): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, DatabaseIncludeSpecialColumns, SystemCols>;
skip(count: number): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, IncludeCount, DatabaseIncludeSpecialColumns, SystemCols>;
expand<TargetTable extends FMTable<any, any>, TSelected extends keyof InferSchemaOutputFromFMTable<TargetTable> | Record<string, Column<any, any, ExtractTableName<TargetTable>>> = keyof InferSchemaOutputFromFMTable<TargetTable>, TNestedExpands extends ExpandedRelations = {}>(targetTable: ValidExpandTarget<Occ, TargetTable>, callback?: (builder: QueryBuilder<TargetTable, keyof InferSchemaOutputFromFMTable<TargetTable>, false, false, {}, false>) => QueryBuilder<TargetTable, TSelected, any, any, TNestedExpands, any, any>): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands & {
[K in ExtractTableName<TargetTable>]: {
schema: InferSchemaOutputFromFMTable<TargetTable>;
selected: TSelected;
nested: TNestedExpands;
};
}, IncludeCount, DatabaseIncludeSpecialColumns, SystemCols>;
single(this: QueryBuilder<Occ, Selected, false, IsCount, Expands, false, DatabaseIncludeSpecialColumns, SystemCols>): QueryBuilder<Occ, Selected, "exact", IsCount, Expands, false, DatabaseIncludeSpecialColumns, SystemCols>;
maybeSingle(this: QueryBuilder<Occ, Selected, false, IsCount, Expands, false, DatabaseIncludeSpecialColumns, SystemCols>): QueryBuilder<Occ, Selected, "maybe", IsCount, Expands, false, DatabaseIncludeSpecialColumns, SystemCols>;
count(this: QueryBuilder<Occ, Selected, false, IsCount, Expands, false, DatabaseIncludeSpecialColumns, SystemCols>): QueryBuilder<Occ, Selected, false, IsCount, Expands, true, DatabaseIncludeSpecialColumns, SystemCols>;
/**
* Builds the OData query string from current query options and expand configs.
*/
private buildQueryString;
execute<EO extends ExecuteOptions>(options?: ExecuteMethodOptions<EO>): Promise<Result<ConditionallyWithODataAnnotations<ConditionallyWithSpecialColumns<QueryReturnType<InferSchemaOutputFromFMTable<Occ>, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>, NormalizeIncludeSpecialColumns<EO["includeSpecialColumns"], DatabaseIncludeSpecialColumns>, Selected extends Record<string, Column<any, any, any>> ? true : Selected extends keyof InferSchemaOutputFromFMTable<Occ> ? false : true>, EO["includeODataAnnotations"] extends true ? true : false>>>;
getQueryString(options?: {
useEntityIds?: boolean;
}): string;
getRequestConfig(): {
method: string;
url: string;
body?: any;
};
toRequest(baseUrl: string, options?: ExecuteOptions): Request;
processResponse(response: Response, options?: ExecuteOptions): Promise<Result<QueryReturnType<InferSchemaOutputFromFMTable<Occ>, Selected, SingleMode, IsCount, Expands, IncludeCount, SystemCols>>>;
}