@jitl/notion-api/src/lib/query.d.ts

The missing companion library for the official Notion public API.

import { QueryDatabaseParameters } from '@notionhq/client/build/src/api-endpoints';
import { EmptyObject, Filter, PartialDatabaseSchema, PropertyFilter, PropertyPointer, PropertySort, PropertyType, Sort, TimestampSort } from './notion-api';
/**
 * Warning: intersecting too many things may break, especially with `keyof`,
 * which often collapses key types to just `string | number | symbol` if the
 * type is too complex.
 */
declare type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;
/**
 * An object mapping from filter operator name to `true`.
 * @category Query
 */
export declare type FilterOperatorTypeMap<T> = {
    [K in keyof UnionToIntersection<T>]: true;
};
/**
 * IDs in the Notion API are strings containing UUIDs.
 *
 * @category API
 */
export declare type IdRequest = string;
/**
 * @category Query
 */
export declare type ExistenceFilterOperator = {
    is_empty: true;
} | {
    is_not_empty: true;
};
/**
 * Runtime type information for [[ExistenceFilterOperator]].
 * @category Query
 */
export declare const EXISTENCE_FILTER_OPERATORS: FilterOperatorTypeMap<ExistenceFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type TextFilterOperator = {
    equals: string;
} | {
    does_not_equal: string;
} | {
    contains: string;
} | {
    does_not_contain: string;
} | {
    starts_with: string;
} | {
    ends_with: string;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[TextFilterOperator]].
 * @category Query
 */
export declare const TEXT_FILTER_OPERATORS: FilterOperatorTypeMap<TextFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type NumberFilterOperator = {
    equals: number;
} | {
    does_not_equal: number;
} | {
    greater_than: number;
} | {
    less_than: number;
} | {
    greater_than_or_equal_to: number;
} | {
    less_than_or_equal_to: number;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[NumberFilterOperator]].
 * @category Query
 */
export declare const NUMBER_FILTER_OPERATORS: FilterOperatorTypeMap<NumberFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type CheckboxFilterOperator = {
    equals: boolean;
} | {
    does_not_equal: boolean;
};
/**
 * Runtime type information for [[NumberFilterOperator]].
 * @category Query
 */
export declare const CHECKBOX_FILTER_OPERATORS: FilterOperatorTypeMap<CheckboxFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type SelectFilterOperator = {
    equals: string;
} | {
    does_not_equal: string;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[SelectFilterOperator]].
 * @category Query
 */
export declare const SELECT_FILTER_OPERATORS: FilterOperatorTypeMap<SelectFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type MultiSelectFilterOperator = {
    contains: string;
} | {
    does_not_contain: string;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[MultiSelectFilterOperator]].
 * @category Query
 */
export declare const MULTI_SELECT_FILTER_OPERATORS: FilterOperatorTypeMap<MultiSelectFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type DateFilterOperator = {
    equals: string;
} | {
    before: string;
} | {
    after: string;
} | {
    on_or_before: string;
} | {
    on_or_after: string;
} | {
    past_week: EmptyObject;
} | {
    past_month: EmptyObject;
} | {
    past_year: EmptyObject;
} | {
    next_week: EmptyObject;
} | {
    next_month: EmptyObject;
} | {
    next_year: EmptyObject;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[DateFilterOperator]].
 * @category Query
 */
export declare const DATE_FILTER_OPERATORS: FilterOperatorTypeMap<DateFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type PeopleFilterOperator = {
    contains: IdRequest;
} | {
    does_not_contain: IdRequest;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[PeopleFilterOperator]].
 * @category Query
 */
export declare const PEOPLE_FILTER_OPERATORS: FilterOperatorTypeMap<PeopleFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type RelationFilterOperator = {
    contains: IdRequest;
} | {
    does_not_contain: IdRequest;
} | ExistenceFilterOperator;
/**
 * Runtime type information for [[RelationFilterOperator]].
 * @category Query
 */
export declare const RELATION_FILTER_OPERATORS: FilterOperatorTypeMap<RelationFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type FormulaFilterOperator = {
    string: TextFilterOperator;
} | {
    checkbox: CheckboxFilterOperator;
} | {
    number: NumberFilterOperator;
} | {
    date: DateFilterOperator;
};
/**
 * Runtime type information for [[FormulaFilterOperator]].
 * @category Query
 */
export declare const FORMULA_FILTER_OPERATORS: FilterOperatorTypeMap<FormulaFilterOperator>;
/**
 * @category Query
 * @source
 */
export declare type RollupSubfilterOperator = {
    rich_text: TextFilterOperator;
} | {
    number: NumberFilterOperator;
} | {
    checkbox: CheckboxFilterOperator;
} | {
    select: SelectFilterOperator;
} | {
    multi_select: MultiSelectFilterOperator;
} | {
    relation: RelationFilterOperator;
} | {
    date: DateFilterOperator;
} | {
    people: PeopleFilterOperator;
} | {
    files: ExistenceFilterOperator;
};
/**
 * @category Query
 * @source
 */
export declare type RollupFilterOperator = {
    any: RollupSubfilterOperator;
} | {
    none: RollupSubfilterOperator;
} | {
    every: RollupSubfilterOperator;
} | {
    date: DateFilterOperator;
} | {
    number: NumberFilterOperator;
};
/**
 * Runtime type information for [[RollupFilterOperator]].
 * @category Query
 */
export declare const ROLLUP_FILTER_OPERATORS: FilterOperatorTypeMap<RollupFilterOperator>;
/**
 * This duplicates [[PropertyFilterDataMap]], but seems more correct.
 * @source
 * @category Query
 */
export declare type PropertyToToFilterOperator = {
    title: TextFilterOperator;
    rich_text: TextFilterOperator;
    number: NumberFilterOperator;
    checkbox: CheckboxFilterOperator;
    select: SelectFilterOperator;
    multi_select: MultiSelectFilterOperator;
    date: DateFilterOperator;
    people: PeopleFilterOperator;
    files: ExistenceFilterOperator;
    url: TextFilterOperator;
    email: TextFilterOperator;
    phone_number: TextFilterOperator;
    relation: RelationFilterOperator;
    created_by: PeopleFilterOperator;
    created_time: DateFilterOperator;
    last_edited_by: PeopleFilterOperator;
    last_edited_time: DateFilterOperator;
    formula: FormulaFilterOperator;
    rollup: RollupFilterOperator;
};
/**
 * Runtime type information for [[PropertyToToFilterOperator]].
 * @category Query
 */
export declare const PROPERTY_FILTER_OPERATORS: {
    [T in PropertyType]: {
        [O in FilterOperatorType<T>]: true;
    };
};
/**
 * @category Database
 */
export declare type FilterOperator<Type extends PropertyType = PropertyType> = PropertyToToFilterOperator[Type];
/**
 * @category Database
 */
export declare type FilterOperatorType<Type extends PropertyType = PropertyType> = keyof UnionToIntersection<FilterOperator<Type>>;
declare type RuntimeFilterOperators = typeof PROPERTY_FILTER_OPERATORS;
declare type FilterOperatorTypesMap = {
    [K in keyof RuntimeFilterOperators]: keyof RuntimeFilterOperators[K];
};
declare type AnyFilterOperator = FilterOperatorTypesMap[keyof FilterOperatorTypesMap];
/**
 * Runtime information for all known filter operators.
 * @category Query
 */
export declare const ALL_PROPERTY_FILTER_OPERATORS: Record<AnyFilterOperator, true>;
declare type FilterOperatorMap = {
    [T in PropertyType]: {
        [O in FilterOperatorType<T>]: UnionToIntersection<FilterOperator<T>>[O];
    };
};
/**
 * Contains a key for each filter operator for this property type.
 * This allows easy tab completion when building filters for a database query.
 *
 * Create with {@link propertyFilterBuilder}, or use one created as part of
 * {@link CMS.filter} or {@link databaseFilterBuilder}.
 *
 * @category Query
 */
export declare type PropertyFilterBuilder<Type extends PropertyType> = {
    schema: PropertyPointer<Type>;
} & {
    [K in FilterOperatorType<Type>]: (value: FilterOperatorMap[Type][K]) => PropertyFilter<Type>;
};
/**
 * Helper object for building [[PropertyFilter]]s for the given `property`.
 * @param property Property to build a filter for.
 * @returns a property filter builder.
 * @category Query
 */
export declare function propertyFilterBuilder<Type extends PropertyType>(property: PropertyPointer<Type>): PropertyFilterBuilder<Type>;
/**
 * Contains a {@link PropertyFilterBuilder} for each property in a {@link PartialDatabaseSchema}.
 *
 * Create one with {@link databaseFilterBuilder}, or use the filter builders from {@link CMS.filter}.
 * @category Query
 */
export declare type DatabaseFilterBuilder<T extends PartialDatabaseSchema> = {
    [K in keyof T]: PropertyFilterBuilder<T[K]['type']>;
} & typeof Filter & {
    schema: T;
};
/**
 * Helper object for building [[PropertyFilter]]s for the properties in the given `schema`.
 * @param schema Database schema to build filters for.
 * @returns A property filter builder for schema property, plus compound filter builders.
 * @category Query
 * @category Database
 */
export declare function databaseFilterBuilder<T extends PartialDatabaseSchema>(schema: T): DatabaseFilterBuilder<T>;
/**
 * @category Query
 */
export interface SortBuilder<T extends Sort> {
    ascending: T & {
        direction: 'ascending';
    };
    descending: T & {
        direction: 'descending';
    };
}
/**
 * @category Query
 */
export interface TimestampSortBuilder {
    created_time: SortBuilder<TimestampSort>;
    last_edited_time: SortBuilder<TimestampSort>;
}
/**
 * For each property in [[PartialDatabaseSchema]]
 *
 * Create one with {@link databaseSortBuilder} or use the sort builders from {@link CMS.sort}.
 *
 * @category Query
 */
export declare type DatabaseSortBuilder<T extends PartialDatabaseSchema> = TimestampSortBuilder & {
    [K in keyof T]: {
        schema: T[K];
    } & SortBuilder<PropertySort>;
};
/**
 * @category Query
 */
export declare function databaseSortBuilder<T extends PartialDatabaseSchema>(schema: T): DatabaseSortBuilder<T>;
/**
 * Extend a base query with additional filters, sorts, etc.
 * Filters will be `and`ed together and sorts concatenated.
 * @category Query
 * @param base
 * @param extension
 * @returns
 */
export declare function extendQueryParameters(base: QueryDatabaseParameters, extension: Partial<QueryDatabaseParameters>): QueryDatabaseParameters;
export {};