ag-grid-url-sync 0.5.0 → 0.5.2

package/dist/core/types.d.ts

@@ -1,4 +1,6 @@
 import type { GridApi as AGGridApi, TextFilterModel, NumberFilterModel, DateFilterModel } from 'ag-grid-community';
+import type { GridView, ViewStore } from './view-storage.js';
+import { type Operator, type OperationsFor } from './operators.js';
 /**
  * Serialization modes for URL parameters
  */
@@ -29,62 +31,100 @@ export type SerializationFormat = 'querystring' | 'json' | 'base64';
  */
 export interface AGGridUrlSyncConfig {
     /**
-     * Prefix for URL parameters (only used in individual mode)
+     * Prefix for URL parameters (only used in individual mode).
+     * A prefix without a trailing `_` gets one, so 'filter' and 'filter_' both
+     * give `?filter_name_contains=john`. An empty prefix means the default.
      * @default 'f_'
      * @example 'filter_' results in URLs like '?filter_name_contains=john'
      */
-    paramPrefix?: string;
+    paramPrefix?: string | undefined;
     /**
      * Maximum length for filter values to prevent URL length issues
      * @default 200
      */
-    maxValueLength?: number;
+    maxValueLength?: number | undefined;
     /**
-     * Optional error handler for parsing errors.
-     * Allows graceful error handling without breaking the application.
+     * Optional handler for issues: a filter that is dropped or not valid, in a
+     * URL, a value, or the grid model. The filter is skipped and the others are
+     * kept. Each error is a `URLSyncError` with a `code` (for example
+     * `VALUE_TOO_LONG`) and, when it is known, a `column`. In the core, an error
+     * from the grid API also comes here, as `GRID_ERROR` (the React hook sends it
+     * to `onError`). A URL that cannot be read is thrown as `INVALID_URL`, not
+     * sent here. The library never writes to the console, so an issue with no
+     * handler is silent (#220).
      *
      * In grouped mode, an error that comes from the grouped URL value is an
      * `InvalidSerializationError`, and the original error is in `error.cause`.
-     * In individual mode, the same failure arrives with no wrapper.
+     * The wrapper has the code and the column of the original issue, so a check
+     * on `error.code` works the same in both modes.
      */
-    onParseError?: (error: Error) => void;
+    onParseError?: ((error: Error) => void) | undefined;
     /**
      * Serialization mode for URL parameters
      * @default 'individual'
      */
-    serialization?: SerializationMode;
+    serialization?: SerializationMode | undefined;
     /**
      * Parameter name for grouped serialization
      * @default 'grid_filters'
      */
-    groupedParam?: string;
+    groupedParam?: string | undefined;
     /**
      * Serialization format for grouped mode
      * @default 'querystring'
      */
-    format?: SerializationFormat;
+    format?: SerializationFormat | undefined;
+    /**
+     * Throw an issue instead of reporting it (#229), like TanStack Query's
+     * `throwOnError`. `true` throws every issue, and a function throws the
+     * issues for which it gives `true`. In the core, a thrown issue is not sent
+     * to `onParseError`, and the first one stops the call. In the React hook,
+     * each issue is still sent to `onParseError` one time, and the picked issue
+     * is thrown during render, so an error boundary catches it. This API does
+     * not change the address bar (only `createGridUrlSync` with `history` does),
+     * so remove the bad param before the boundary resets, or the same issue is
+     * thrown again.
+     *
+     * A function that throws makes the library throw that error.
+     * @default false
+     */
+    throwOnError?: boolean | ((issue: URLSyncError) => boolean) | undefined;
 }
+/**
+ * The options with a value for each one: the config after the defaults are
+ * filled in. It has no `gridApi`: the grid is an argument of the functions
+ * that read it (#219).
+ *
+ * A caller can set an option to undefined (#258), so `Required` is not enough:
+ * it keeps the undefined.
+ */
+export type ResolvedOptions = {
+    [K in Exclude<keyof AGGridUrlSyncConfig, 'throwOnError'>]-?: Exclude<AGGridUrlSyncConfig[K], undefined>;
+} & {
+    /**
+     * Optional, so that ParseConfig and InternalConfig, which extend this type,
+     * get no new required key (#229). resolveOptions always sets it.
+     */
+    throwOnError?: Exclude<AGGridUrlSyncConfig['throwOnError'], undefined>;
+};
 /**
  * Configuration for URL parsing and serialization operations that don't require GridApi.
- * Use this type when you only need to parse filters from URLs or serialize filters to URLs
- * without actually applying them to a grid.
  *
- * @example
- * ```typescript
- * // Parse filters without a grid instance
- * const config: ParseConfig = {
- *   ...DEFAULT_CONFIG,
- *   onParseError: (error) => console.error(error)
- * }
- * const filters = parseUrlFilters(url, config)
- * ```
+ * @deprecated The parse and serialize functions take a partial
+ * `AGGridUrlSyncConfig` and fill in the defaults, so you do not need this
+ * type. Use `ResolvedOptions` for a config with every option set. This type
+ * will be removed in 0.6.0.
  */
-export interface ParseConfig extends Required<AGGridUrlSyncConfig> {
+export interface ParseConfig extends ResolvedOptions {
     /** AG Grid API instance - not read by parsing/serialization operations */
     gridApi?: AGGridApi | null;
 }
 /**
  * Internal configuration with all required fields and runtime dependencies
+ *
+ * @deprecated Give the grid API to `getFilterModel(gridApi, options)` and
+ * `applyFilterModel(filterState, gridApi, options)` as an argument. This type
+ * will be removed in 0.6.0.
  */
 export interface InternalConfig extends ParseConfig {
     /** AG Grid API instance for filter operations */
@@ -93,23 +133,23 @@ export interface InternalConfig extends ParseConfig {
 /**
  * Text-only filter operations for string-based filtering
  */
-export declare const TEXT_ONLY_OPERATIONS: readonly ['contains', 'notContains', 'startsWith', 'endsWith'];
+export declare const TEXT_ONLY_OPERATIONS: readonly ["contains", "notContains", "startsWith", "endsWith"];
 /**
  * Number-only filter operations for numeric comparisons
  */
-export declare const NUMBER_ONLY_OPERATIONS: readonly ['lessThan', 'lessThanOrEqual', 'greaterThan', 'greaterThanOrEqual', 'inRange'];
+export declare const NUMBER_ONLY_OPERATIONS: readonly ["lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual", "inRange"];
 /**
  * Date-specific filter operations for temporal comparisons
  */
-export declare const DATE_ONLY_OPERATIONS: readonly ['dateBefore', 'dateBeforeOrEqual', 'dateAfter', 'dateAfterOrEqual', 'dateRange'];
+export declare const DATE_ONLY_OPERATIONS: readonly ["dateBefore", "dateBeforeOrEqual", "dateAfter", "dateAfterOrEqual", "dateRange"];
 /**
  * Operations shared across multiple filter types
  */
-export declare const SHARED_OPERATIONS: readonly ['eq', 'notEqual', 'blank', 'notBlank'];
+export declare const SHARED_OPERATIONS: readonly ["eq", "notEqual", "blank", "notBlank"];
 /**
  * All supported filter operations across text, number, and date filters
  */
-export type FilterOperation = (typeof TEXT_ONLY_OPERATIONS)[number] | (typeof NUMBER_ONLY_OPERATIONS)[number] | (typeof DATE_ONLY_OPERATIONS)[number] | (typeof SHARED_OPERATIONS)[number];
+export type FilterOperation = Operator['id'];
 /**
  * Complete list of valid text filter operations
  */
@@ -119,29 +159,33 @@ export declare const TEXT_FILTER_OPERATIONS: readonly ["contains", "notContains"
  */
 export declare const NUMBER_FILTER_OPERATIONS: readonly ["lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual", "inRange", "eq", "notEqual", "blank", "notBlank"];
 /**
- * Valid date filter operations as const array
+ * Valid date filter operations
  */
 export declare const DATE_FILTER_OPERATIONS: readonly ["dateBefore", "dateBeforeOrEqual", "dateAfter", "dateAfterOrEqual", "dateRange", "eq", "notEqual", "blank", "notBlank"];
 /**
  * Text-specific filter operations
  */
-export type TextFilterOperation = (typeof TEXT_FILTER_OPERATIONS)[number];
+export type TextFilterOperation = OperationsFor<'text'>;
 /**
  * Number-specific filter operations
  */
-export type NumberFilterOperation = (typeof NUMBER_FILTER_OPERATIONS)[number];
+export type NumberFilterOperation = OperationsFor<'number'>;
 /**
  * Date-specific filter operations
  */
-export type DateFilterOperation = (typeof DATE_FILTER_OPERATIONS)[number];
+export type DateFilterOperation = OperationsFor<'date'>;
 /**
  * Range operations that require two values (from/to)
  */
-export type RangeOperation = 'inRange' | 'dateRange';
+export type RangeOperation = Extract<Operator, {
+    arity: 2;
+}>['id'];
 /**
  * Operations that don't require a filter value
  */
-export type BlankOperation = 'blank' | 'notBlank';
+export type BlankOperation = Extract<Operator, {
+    arity: 0;
+}>['id'];
 /**
  * Supported filter types
  */
@@ -224,35 +268,67 @@ export declare function isNumberFilter(filter: ColumnFilter): filter is NumberCo
  * Type guard to check if a filter is a date filter
  */
 export declare function isDateFilter(filter: ColumnFilter): filter is DateColumnFilter;
+/**
+ * The reason for an issue (#220). Data issues are a filter that is dropped or
+ * not valid. The other codes are failures of an operation.
+ */
+export type IssueCode = 'INVALID_PARAM' | 'INVALID_NUMBER' | 'INVALID_DATE' | 'VALUE_TOO_LONG' | 'INVALID_GROUPED' | 'TYPE_MISMATCH' | 'INVALID_URL' | 'GRID_ERROR' | 'NOT_READY' | 'VIEW_NOT_FOUND' | 'VIEW_NAME_REQUIRED' | 'STORAGE_UNAVAILABLE' | 'STORAGE_FULL' | 'STORAGE_WRITE_FAILED' | 'HISTORY_WRITE_FAILED' | 'UNKNOWN';
+/**
+ * How bad an issue is (#221). A `'warning'` is a data issue: the sync goes on
+ * and the bad filter (or the bad URL) is left out. An `'error'` is an
+ * operation that failed.
+ */
+export type IssueSeverity = 'error' | 'warning';
+/** The code and the column of an issue, when the default is not right */
+export interface IssueDetails {
+    code?: IssueCode | undefined;
+    column?: string | undefined;
+}
 /**
  * Base error class for all URL sync operations
  */
 export declare class URLSyncError extends Error {
     readonly cause?: Error | undefined;
-    constructor(message: string, cause?: Error | undefined);
+    /** The reason for the error */
+    readonly code: IssueCode;
+    /** The column of the filter, when it is known */
+    readonly column?: string;
+    constructor(message: string, cause?: Error | undefined, details?: IssueDetails);
+    /**
+     * How bad the issue is, from its code (#221). A getter, so it is not an own
+     * property and `toEqual` comparisons of errors do not change.
+     */
+    get severity(): IssueSeverity;
 }
 /**
  * Error thrown when filter validation fails
  */
 export declare class InvalidFilterError extends URLSyncError {
-    constructor(message: string, cause?: Error);
+    constructor(message: string, cause?: Error, details?: IssueDetails);
 }
 /**
  * Error thrown when URL parsing fails
  */
 export declare class InvalidURLError extends URLSyncError {
-    constructor(message: string, cause?: Error);
+    constructor(message: string, cause?: Error, details?: IssueDetails);
 }
 /**
  * Error thrown when date validation fails
  */
 export declare class InvalidDateError extends InvalidFilterError {
-    constructor(message: string, cause?: Error);
+    constructor(message: string, cause?: Error, details?: IssueDetails);
 }
 /**
- * Error thrown when serialization/deserialization fails
- */
-export declare class InvalidSerializationError extends Error {
+ * Error thrown when serialization/deserialization fails.
+ *
+ * When the cause is an issue inside the grouped value (for example a value
+ * over maxValueLength), this error has the same code and column, so a filter
+ * gives the same code in both modes. `INVALID_GROUPED` means that the grouped
+ * value itself does not decode.
+ */
+export declare class InvalidSerializationError extends URLSyncError {
+    /** The grouped format: querystring, json or base64 */
+    readonly format: string;
     constructor(format: string, cause: Error);
 }
 /**
@@ -286,6 +362,28 @@ export interface RawAGGridFilter {
     dateFrom?: string;
     dateTo?: string;
 }
+/**
+ * The URL with the current filter state, and whether the grid has filters
+ */
+export interface UrlState {
+    /** The URL with the current filter state and the page's own params */
+    url: string;
+    /** Whether the grid has filters that the library supports */
+    hasFilters: boolean;
+    /**
+     * The issues of this call (#229): filters that the grid read or the URL
+     * leaves out. The same objects also go to `onParseError`.
+     */
+    issues: readonly URLSyncError[];
+}
+/** The result of an apply method (#229) */
+export interface ApplyResult {
+    /**
+     * The issues of this call: filters that were dropped. The same objects
+     * also go to `onParseError`.
+     */
+    issues: readonly URLSyncError[];
+}
 /**
  * Grouped serialization result
  */
@@ -305,14 +403,14 @@ export interface FormatSerializer {
      * maxValueLength and onParseError. JSON and Base64 drop over-length text
      * values and report them through onParseError (see #213, #207).
      */
-    serialize(filterState: FilterState, config?: ParseConfig): string;
+    serialize(filterState: FilterState, config?: ResolvedOptions): string;
     /**
      * Deserialize string to filter state
      * @param config - Caller's configuration. All serializers honour
      * maxValueLength and onParseError. JSON and Base64 drop over-length text
      * values and report them through onParseError (see #213, #207).
      */
-    deserialize(value: string, config?: ParseConfig): FilterState;
+    deserialize(value: string, config?: ResolvedOptions): FilterState;
     /** Format identifier */
     format: SerializationFormat;
 }
@@ -329,20 +427,175 @@ export interface GroupedDetectionResult {
     /** The raw value if grouped */
     value?: string;
 }
+/**
+ * Operation Mapping Strategy:
+ *
+ * We use three different naming conventions for better user experience:
+ *
+ * 1. URL Parameters: Short, clean names for URLs (e.g., 'eq', 'neq', 'before', 'after')
+ * 2. Internal Types: Consistent naming for our FilterOperation type
+ * 3. AG Grid Operations: Exact names expected by AG Grid API (e.g., 'equals', 'notEqual', 'lessThan')
+ *
+ * The operator table in `operators.ts` holds all three names for each
+ * operation (#217). The maps below are derived from it and kept only for
+ * callers that use them.
+ */
 /**
  * Maps URL operation names to internal operation types
+ * @deprecated Derived from the operator table. Will be removed in 0.6.0.
  */
 export declare const OPERATION_MAP: Record<string, FilterOperation>;
 /**
  * Maps internal operation types to URL operation names
+ * @deprecated Derived from the operator table. Will be removed in 0.6.0.
  */
 export declare const INTERNAL_TO_URL_OPERATION_MAP: Record<FilterOperation, string>;
 /**
  * Maps internal operation types to AG Grid operation names
+ * @deprecated Derived from the operator table. Will be removed in 0.6.0.
  */
 export declare const AG_GRID_OPERATION_NAMES: Record<string, string>;
 /**
- * Maps AG Grid operation names to internal operation types
+ * Maps AG Grid operation names to internal operation types.
+ *
+ * AG Grid uses one name for a number and a date operation, so this map is
+ * wrong for one of them: `lessThan` gives `dateBefore`. The last row in the
+ * operator table wins, as before.
+ * @deprecated The key needs the filter type too. Will be removed in 0.6.0.
  */
 export declare const REVERSE_AG_GRID_OPERATION_NAMES: Record<string, FilterOperation>;
+declare const codecBrand: unique symbol;
+/**
+ * How the filters are written in the URL. Make one with `individual()` or
+ * `grouped()`. It is opaque: only `createGridUrlSync` reads it.
+ */
+export interface Codec {
+    readonly [codecBrand]: true;
+}
+/**
+ * The state of a sync. `'idle'`: there is no sync yet (the React hook uses
+ * it). `'active'`: the sync listens to the grid. `'destroyed'`: after
+ * `destroy()`, or after the grid is destroyed.
+ */
+export type SyncStatus = 'idle' | 'active' | 'destroyed';
+/**
+ * Where the work that found an issue started. `'url'`: the sync read the
+ * address bar itself (on create, or on `popstate`). `'grid'`: the sync read
+ * the grid after a filter change. `'api'`: a method that the app called.
+ */
+export type IssueSource = 'url' | 'grid' | 'api';
+/** The one argument of `onIssue` */
+export interface IssueEvent {
+    issue: URLSyncError;
+    source: IssueSource;
+}
+/**
+ * The state of a sync, for `useSyncExternalStore` and for apps. The same
+ * object is returned until something in it changes.
+ */
+export interface GridUrlSyncSnapshot {
+    readonly status: SyncStatus;
+    /** The URL with the grid's filters and the page's own params */
+    readonly url: string;
+    /** Whether the grid has filters that the library supports */
+    readonly hasFilters: boolean;
+    /** The issues of the latest apply and of the latest grid read */
+    readonly issues: readonly URLSyncError[];
+    /** The saved views, in save order. Empty with no `views` option. */
+    readonly views: readonly GridView[];
+    /** The id of the active saved view, or null */
+    readonly activeViewId: string | null;
+}
+/**
+ * How the sync writes a filter change to the address bar: a user edit, a
+ * view load or `applyFilters`. A URL apply writes nothing. `'none'` never
+ * writes. `'replace'` and `'push'` use `window.history`. A function gets the
+ * URL, for example `url => router.replace(url)`.
+ */
+export type HistoryMode = 'none' | 'replace' | 'push' | ((url: string) => void);
+/** The options of `createGridUrlSync` */
+export interface GridUrlSyncOptions {
+    /** The AG Grid API */
+    api: AGGridApi;
+    /**
+     * How the filters are written in the URL
+     * @default individual()
+     */
+    codec?: Codec | undefined;
+    /**
+     * Maximum length for a filter value
+     * @default 200
+     */
+    maxValueLength?: number | undefined;
+    /** @default 'none' */
+    history?: HistoryMode | undefined;
+    /**
+     * Apply the URL when the browser's back or forward button changes it
+     * @default true when `history` is `'push'`, else false
+     */
+    popstate?: boolean | undefined;
+    /**
+     * Apply the address bar's filters when the sync is made. A URL with no
+     * filters keeps the grid's filters.
+     * @default true
+     */
+    applyUrlOnCreate?: boolean | undefined;
+    /**
+     * Throw an issue instead of reporting it, in the methods that the app
+     * calls (`applyUrl`, `applyFilters`, `getUrl`, `saveView`, `loadView`,
+     * `deleteView`). `createGridUrlSync` and the sync's own listeners never
+     * throw.
+     * @default false
+     */
+    throwOnError?: boolean | ((issue: URLSyncError) => boolean) | undefined;
+    /** Gets each issue one time */
+    onIssue?: ((event: IssueEvent) => void) | undefined;
+    /**
+     * The saved views. Give `createViewStore(key)` from
+     * `ag-grid-url-sync/view-storage`, or your own `ViewStore`. With no
+     * store, `views` is empty and the view methods do nothing. On create, a
+     * URL that holds the stored view restores it, else a URL with at least
+     * one filter wins, else the stored view is restored.
+     */
+    views?: ViewStore | undefined;
+}
+/** A sync between one grid and the URL */
+export interface GridUrlSync {
+    /** The current state. The same object until something changes. */
+    getSnapshot(): GridUrlSyncSnapshot;
+    /** Calls the listener after each snapshot change. Returns unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Applies the filters of a URL (default: the address bar) to the grid */
+    applyUrl(url?: string): ApplyResult;
+    /**
+     * Applies filters to the grid as the app's own write. When it lands, the
+     * URL is written in the `history` mode, as for a user edit.
+     */
+    applyFilters(filters: FilterState): ApplyResult;
+    /** The URL with the grid's filters (default base: the address bar) */
+    getUrl(baseUrl?: string): string;
+    /**
+     * Saves the grid's filters as a view with this name, and makes it active.
+     * The same name updates that view. Returns null with no `views` option or
+     * when the save fails.
+     */
+    saveView(name: string): GridView | null;
+    /**
+     * Loads a saved view into the grid and makes it active. `null` clears the
+     * filters. When the view lands, the URL is written in the `history` mode,
+     * as for a user edit. An unknown id reports `VIEW_NOT_FOUND`.
+     */
+    loadView(id: string | null): void;
+    /**
+     * Deletes a saved view. If it is active and the grid still shows it, the
+     * grid is cleared.
+     */
+    deleteView(id: string): void;
+    /**
+     * Removes the listeners. The snapshot keeps the last state. After this,
+     * `applyUrl`, `applyFilters`, `saveView` and `loadView` report
+     * `NOT_READY`.
+     */
+    destroy(): void;
+}
 export {};

package/dist/core/types.js

@@ -1,55 +1,27 @@
-export const TEXT_ONLY_OPERATIONS = [
-    'contains',
-    'notContains',
-    'startsWith',
-    'endsWith'
-];
-export const NUMBER_ONLY_OPERATIONS = [
-    'lessThan',
-    'lessThanOrEqual',
-    'greaterThan',
-    'greaterThanOrEqual',
-    'inRange'
-];
-export const DATE_ONLY_OPERATIONS = [
-    'dateBefore',
-    'dateBeforeOrEqual',
-    'dateAfter',
-    'dateAfterOrEqual',
-    'dateRange'
-];
-export const SHARED_OPERATIONS = [
-    'eq',
-    'notEqual',
-    'blank',
-    'notBlank'
-];
-export const TEXT_FILTER_OPERATIONS = [
-    ...TEXT_ONLY_OPERATIONS,
-    ...SHARED_OPERATIONS
-];
-export const NUMBER_FILTER_OPERATIONS = [
-    ...NUMBER_ONLY_OPERATIONS,
-    ...SHARED_OPERATIONS
-];
-export const DATE_FILTER_OPERATIONS = [
-    ...DATE_ONLY_OPERATIONS,
-    ...SHARED_OPERATIONS
-];
+import { attachColumn } from './issue-columns.js';
+import { DATA_ISSUE_CODES } from './data-issue-codes.js';
+import { OPERATORS, operationsFor, operationsOnlyFor, sharedOperations, isOperationFor, operatorById } from './operators.js';
+export const TEXT_ONLY_OPERATIONS = operationsOnlyFor('text');
+export const NUMBER_ONLY_OPERATIONS = operationsOnlyFor('number');
+export const DATE_ONLY_OPERATIONS = operationsOnlyFor('date');
+export const SHARED_OPERATIONS = sharedOperations();
+export const TEXT_FILTER_OPERATIONS = operationsFor('text');
+export const NUMBER_FILTER_OPERATIONS = operationsFor('number');
+export const DATE_FILTER_OPERATIONS = operationsFor('date');
 export function isTextFilterOperation(op) {
-    return TEXT_FILTER_OPERATIONS.includes(op);
+    return isOperationFor(op, 'text');
 }
 export function isNumberFilterOperation(op) {
-    return NUMBER_FILTER_OPERATIONS.includes(op);
+    return isOperationFor(op, 'number');
 }
 export function isDateFilterOperation(op) {
-    return DATE_FILTER_OPERATIONS.includes(op);
+    return isOperationFor(op, 'date');
 }
 export function isRangeOperation(op) {
-    return op === 'inRange' || op === 'dateRange';
+    return operatorById(op)?.arity === 2;
 }
 export function isBlankOperation(op) {
-    return op === 'blank' || op === 'notBlank';
+    return operatorById(op)?.arity === 0;
 }
 export function isTextFilter(filter) {
     return filter.filterType === 'text';
@@ -62,90 +34,49 @@ export function isDateFilter(filter) {
 }
 export class URLSyncError extends Error {
     cause;
-    constructor(message, cause) {
+    code;
+    constructor(message, cause, details = {}) {
         super(message);
         this.cause = cause;
         this.name = 'URLSyncError';
+        this.code = details.code ?? 'UNKNOWN';
+        if (details.column !== undefined)
+            attachColumn(this, details.column);
+    }
+    get severity() {
+        return DATA_ISSUE_CODES.has(this.code) ? 'warning' : 'error';
     }
 }
 export class InvalidFilterError extends URLSyncError {
-    constructor(message, cause) {
-        super(message, cause);
+    constructor(message, cause, details = {}) {
+        super(message, cause, { ...details, code: details.code ?? 'INVALID_PARAM' });
         this.name = 'InvalidFilterError';
     }
 }
 export class InvalidURLError extends URLSyncError {
-    constructor(message, cause) {
-        super(message, cause);
+    constructor(message, cause, details = {}) {
+        super(message, cause, { ...details, code: details.code ?? 'INVALID_URL' });
         this.name = 'InvalidURLError';
     }
 }
 export class InvalidDateError extends InvalidFilterError {
-    constructor(message, cause) {
-        super(message, cause);
+    constructor(message, cause, details = {}) {
+        super(message, cause, { ...details, code: details.code ?? 'INVALID_DATE' });
         this.name = 'InvalidDateError';
     }
 }
-export class InvalidSerializationError extends Error {
+export class InvalidSerializationError extends URLSyncError {
+    format;
     constructor(format, cause) {
-        super(`Invalid ${format} serialization: ${cause.message}`);
+        super(`Invalid ${format} serialization: ${cause.message}`, cause, cause instanceof URLSyncError
+            ? { code: cause.code, column: cause.column }
+            : { code: 'INVALID_GROUPED' });
         this.name = 'InvalidSerializationError';
-        this.cause = cause;
+        this.format = format;
     }
 }
-const URL_SHORTHAND_MAPPINGS = {
-    notEqual: 'neq',
-    lessThan: 'lt',
-    lessThanOrEqual: 'lte',
-    greaterThan: 'gt',
-    greaterThanOrEqual: 'gte',
-    inRange: 'range',
-    dateBefore: 'before',
-    dateBeforeOrEqual: 'beforeEq',
-    dateAfter: 'after',
-    dateAfterOrEqual: 'afterEq',
-    dateRange: 'daterange'
-};
-const AG_GRID_NAME_MAPPINGS = {
-    eq: 'equals',
-    dateBefore: 'lessThan',
-    dateBeforeOrEqual: 'lessThanOrEqual',
-    dateAfter: 'greaterThan',
-    dateAfterOrEqual: 'greaterThanOrEqual',
-    dateRange: 'inRange'
-};
-function createOperationMaps() {
-    const allOperations = [
-        ...TEXT_FILTER_OPERATIONS,
-        ...NUMBER_FILTER_OPERATIONS,
-        ...DATE_FILTER_OPERATIONS
-    ];
-    const uniqueOperations = [...new Set(allOperations)];
-    const operationMap = {};
-    const internalToUrlMap = {};
-    uniqueOperations.forEach(operation => {
-        const urlName = URL_SHORTHAND_MAPPINGS[operation] || operation;
-        operationMap[urlName] = operation;
-        internalToUrlMap[operation] = urlName;
-    });
-    const agGridMap = {};
-    const reverseAgGridMap = {};
-    uniqueOperations.forEach(operation => {
-        const agGridName = AG_GRID_NAME_MAPPINGS[operation] ||
-            operation;
-        agGridMap[operation] = agGridName;
-        reverseAgGridMap[agGridName] = operation;
-    });
-    return {
-        operationMap,
-        internalToUrlMap,
-        agGridMap,
-        reverseAgGridMap
-    };
-}
-const mappings = createOperationMaps();
-export const OPERATION_MAP = mappings.operationMap;
-export const INTERNAL_TO_URL_OPERATION_MAP = mappings.internalToUrlMap;
-export const AG_GRID_OPERATION_NAMES = mappings.agGridMap;
-export const REVERSE_AG_GRID_OPERATION_NAMES = mappings.reverseAgGridMap;
+export const OPERATION_MAP = Object.fromEntries(OPERATORS.map(op => [op.url, op.id]));
+export const INTERNAL_TO_URL_OPERATION_MAP = Object.fromEntries(OPERATORS.map(op => [op.id, op.url]));
+export const AG_GRID_OPERATION_NAMES = Object.fromEntries(OPERATORS.map(op => [op.id, op.agGrid]));
+export const REVERSE_AG_GRID_OPERATION_NAMES = Object.fromEntries(OPERATORS.map(op => [op.agGrid, op.id]));
 //# sourceMappingURL=types.js.map