ag-grid-url-sync 0.5.0 → 0.5.2

package/dist/core/ag-grid-url-sync.d.ts

@@ -1,10 +1,15 @@
 import type { GridApi } from 'ag-grid-community';
-import type { AGGridUrlSyncConfig, FilterState, SerializationFormat, SerializationMode } from './types.js';
+import type { AGGridUrlSyncConfig, FilterState, ApplyResult, SerializationFormat, SerializationMode, UrlState } from './types.js';
 /**
  * AGGridUrlSync class for synchronizing AG Grid text filters with URL parameters
+ *
+ * @deprecated Use `createGridUrlSync({ api })`: it also listens to the grid
+ * and can write the address bar (#221). `AGGridUrlSync` and `createUrlSync`
+ * will be removed in 0.6.0.
  */
 export declare class AGGridUrlSync {
-    private config;
+    private readonly gridApi;
+    private readonly options;
     /**
      * Creates a new instance of AGGridUrlSync
      * @param gridApi - AG Grid API instance
@@ -26,10 +31,7 @@ export declare class AGGridUrlSync {
      * also keeps the page's own params (#215).
      * @param baseUrl - Optional base URL (defaults to current URL)
      */
-    getUrlState(baseUrl?: string): {
-        url: string;
-        hasFilters: boolean;
-    };
+    getUrlState(baseUrl?: string): UrlState;
     /**
      * Gets the current filter state as URL query parameters
      * @returns Query parameter string
@@ -38,17 +40,20 @@ export declare class AGGridUrlSync {
     /**
      * Applies filters from a URL to the grid
      * @param url - Optional URL to parse (defaults to current URL)
+     * @returns The issues of this call: filters in the URL that were dropped
      */
-    applyFromUrl(url?: string): void;
+    applyFromUrl(url?: string): ApplyResult;
     /**
      * Applies a filter state object to the grid
      * @param filterState - Filter state to apply
+     * @returns The issues of this call: filters that were dropped
      */
-    applyFilters(filterState: FilterState): void;
+    applyFilters(filterState: FilterState): ApplyResult;
     /**
      * Clears all text filters from the grid
+     * @returns The issues of this call
      */
-    clearFilters(): void;
+    clearFilters(): ApplyResult;
     /**
      * Cleans up any resources or event listeners
      */
@@ -74,5 +79,7 @@ export declare class AGGridUrlSync {
  * @param gridApi - AG Grid API instance
  * @param config - Optional configuration options
  * @returns AGGridUrlSync instance
+ * @deprecated Use `createGridUrlSync({ api })` (#221). This function will be
+ * removed in 0.6.0.
  */
 export declare function createUrlSync(gridApi: GridApi, config?: AGGridUrlSyncConfig): AGGridUrlSync;

package/dist/core/ag-grid-url-sync.js

@@ -1,27 +1,27 @@
-import { DEFAULT_CONFIG } from './validation.js';
+import { resolveOptions } from './options.js';
+import { collectIssues } from './issues.js';
 import { parseUrlFilters } from './url-parser.js';
 import { generateUrl } from './url-generator.js';
 import { getFilterModel, applyFilterModel } from './grid-integration.js';
 import { serializeGrouped } from './serialization/grouped.js';
 export class AGGridUrlSync {
-    config;
+    gridApi;
+    options;
     constructor(gridApi, config = {}) {
-        const definedConfig = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
-        this.config = {
-            gridApi,
-            ...DEFAULT_CONFIG,
-            ...definedConfig
-        };
+        this.gridApi = gridApi;
+        this.options = resolveOptions(config);
     }
     generateUrl(baseUrl) {
         return this.getUrlState(baseUrl).url;
     }
     getUrlState(baseUrl) {
-        const filterState = getFilterModel(this.config);
+        const { options, issues } = collectIssues(this.options);
+        const filterState = getFilterModel(this.gridApi, options);
         const url = baseUrl ?? window.location.href;
         return {
-            url: generateUrl(url, filterState, this.config),
-            hasFilters: Object.keys(filterState).length > 0
+            url: generateUrl(url, filterState, options),
+            hasFilters: Object.keys(filterState).length > 0,
+            issues
         };
     }
     getQueryParams() {
@@ -30,28 +30,32 @@ export class AGGridUrlSync {
         return urlObj.search;
     }
     applyFromUrl(url) {
+        const { options, issues } = collectIssues(this.options);
         const urlToParse = url ?? window.location.href;
-        const filterState = parseUrlFilters(urlToParse, this.config);
-        this.applyFilters(filterState);
+        const filterState = parseUrlFilters(urlToParse, options);
+        const applied = this.applyFilters(filterState);
+        return { issues: [...issues, ...(applied?.issues ?? [])] };
     }
     applyFilters(filterState) {
-        applyFilterModel(filterState, this.config);
+        const { options, issues } = collectIssues(this.options);
+        applyFilterModel(filterState, this.gridApi, options);
+        return { issues };
     }
     clearFilters() {
-        this.applyFilters({});
+        return this.applyFilters({});
     }
     destroy() {
     }
     getSerializationMode() {
-        return this.config.serialization;
+        return this.options.serialization;
     }
     getCurrentFormat() {
-        return this.config.format;
+        return this.options.format;
     }
     getFiltersAsFormat(format) {
-        const filterState = getFilterModel(this.config);
+        const filterState = getFilterModel(this.gridApi, this.options);
         const tempConfig = {
-            ...this.config,
+            ...this.options,
             format,
             serialization: 'grouped'
         };

package/dist/core/ag-grid-url-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"ag-grid-url-sync.js","sourceRoot":"","sources":["../../src/core/ag-grid-url-sync.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAK7D,MAAM,OAAO,aAAa;IAChB,MAAM,CAAgB;IAO9B,YAAY,OAAgB,EAAE,MAAM,GAAwB,EAAE;QAI5D,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAC3C,CAAA;QAExB,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO;YACP,GAAG,cAAc;YACjB,GAAG,aAAa;SACjB,CAAA;IACH,CAAC;IAOD,WAAW,CAAC,OAAgB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,CAAA;IACtC,CAAC;IAWD,WAAW,CAAC,OAAgB;QAC1B,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC/C,MAAM,GAAG,GAAG,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC3C,OAAO;YACL,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;YAC/C,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;SAChD,CAAA;IACH,CAAC;IAMD,cAAc;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAA;IACtB,CAAC;IAMD,YAAY,CAAC,GAAY;QACvB,MAAM,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC9C,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5D,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;IAChC,CAAC;IAMD,YAAY,CAAC,WAAwB;QACnC,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAKD,YAAY;QACV,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IACvB,CAAC;IAKD,OAAO;IAEP,CAAC;IAMD,oBAAoB;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAA;IAClC,CAAC;IAMD,gBAAgB;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAA;IAC3B,CAAC;IAKD,kBAAkB,CAAC,MAA2B;QAC5C,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAG/C,MAAM,UAAU,GAAG;YACjB,GAAG,IAAI,CAAC,MAAM;YACd,MAAM;YACN,aAAa,EAAE,SAAkB;SAClC,CAAA;QAGD,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;QAExD,OAAO,MAAM,CAAC,KAAK,CAAA;IACrB,CAAC;CACF;AAQD,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,MAA4B;IAE5B,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC"}
+{"version":3,"file":"ag-grid-url-sync.js","sourceRoot":"","sources":["../../src/core/ag-grid-url-sync.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAS7D,MAAM,OAAO,aAAa;IACP,OAAO,CAAS;IAChB,OAAO,CAAiB;IAOzC,YAAY,OAAgB,EAAE,MAAM,GAAwB,EAAE;QAC5D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QAGtB,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;IACvC,CAAC;IAOD,WAAW,CAAC,OAAgB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,CAAA;IACtC,CAAC;IAWD,WAAW,CAAC,OAAgB;QAC1B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACvD,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACzD,MAAM,GAAG,GAAG,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAE3C,OAAO;YACL,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC;YAC3C,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;YAC/C,MAAM;SACP,CAAA;IACH,CAAC;IAMD,cAAc;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QAE3B,OAAO,MAAM,CAAC,MAAM,CAAA;IACtB,CAAC;IAOD,YAAY,CAAC,GAAY;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACvD,MAAM,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC9C,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;QAIxD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;QAE9C,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,EAAE,CAAA;IAC5D,CAAC;IAOD,YAAY,CAAC,WAAwB;QACnC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACvD,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAEpD,OAAO,EAAE,MAAM,EAAE,CAAA;IACnB,CAAC;IAMD,YAAY;QACV,OAAO,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IAC9B,CAAC;IAKD,OAAO;IAEP,CAAC;IAMD,oBAAoB;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAA;IACnC,CAAC;IAMD,gBAAgB;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAA;IAC5B,CAAC;IAKD,kBAAkB,CAAC,MAA2B;QAC5C,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QAG9D,MAAM,UAAU,GAAG;YACjB,GAAG,IAAI,CAAC,OAAO;YACf,MAAM;YACN,aAAa,EAAE,SAAkB;SAClC,CAAA;QAGD,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;QAExD,OAAO,MAAM,CAAC,KAAK,CAAA;IACrB,CAAC;CACF;AAUD,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,MAA4B;IAE5B,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC"}

package/dist/core/codecs.d.ts

@@ -0,0 +1,28 @@
+import type { Codec, ResolvedOptions, SerializationFormat } from './types.js';
+/** The options that a codec sets */
+export type CodecOptions = Pick<ResolvedOptions, 'serialization' | 'paramPrefix' | 'groupedParam' | 'format'>;
+/**
+ * One URL param for each filter, for example `?f_name_contains=jo`
+ * @param options.prefix - The start of each param name. Default `'f_'`.
+ */
+export declare function individual(options?: {
+    prefix?: string | undefined;
+}): Codec;
+/**
+ * All the filters in one URL param
+ * @param options.param - The param name. Default `'grid_filters'`.
+ * @param options.format - `'querystring'` (default), `'json'` or `'base64'`
+ */
+export declare function grouped(options?: {
+    param?: string | undefined;
+    format?: SerializationFormat | undefined;
+}): Codec;
+/** The options of a codec. Throws for an object that no factory made. */
+export declare function codecOptions(codec: Codec): CodecOptions;
+/**
+ * A codec with all four settings, for the React hook (#222). Internal: the
+ * hook's old options name the params of both modes, and the URL must strip
+ * the names that the app set, as the class does. Not exported from the
+ * package.
+ */
+export declare function codecFromOptions(options: CodecOptions): Codec;

package/dist/core/codecs.js

@@ -0,0 +1,39 @@
+import { DEFAULT_CONFIG } from './options.js';
+const settings = new WeakMap();
+function makeCodec(options) {
+    const codec = Object.freeze({});
+    settings.set(codec, options);
+    return codec;
+}
+export function individual(options = {}) {
+    return makeCodec({
+        serialization: 'individual',
+        paramPrefix: options.prefix ?? DEFAULT_CONFIG.paramPrefix,
+        groupedParam: DEFAULT_CONFIG.groupedParam,
+        format: DEFAULT_CONFIG.format
+    });
+}
+export function grouped(options = {}) {
+    return makeCodec({
+        serialization: 'grouped',
+        paramPrefix: DEFAULT_CONFIG.paramPrefix,
+        groupedParam: options.param ?? DEFAULT_CONFIG.groupedParam,
+        format: options.format ?? DEFAULT_CONFIG.format
+    });
+}
+export function codecOptions(codec) {
+    const options = settings.get(codec);
+    if (!options) {
+        throw new TypeError('codec must come from individual() or grouped()');
+    }
+    return options;
+}
+export function codecFromOptions(options) {
+    return makeCodec({
+        serialization: options.serialization,
+        paramPrefix: options.paramPrefix,
+        groupedParam: options.groupedParam,
+        format: options.format
+    });
+}
+//# sourceMappingURL=codecs.js.map

package/dist/core/codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.js","sourceRoot":"","sources":["../../src/core/codecs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAY7C,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAuB,CAAA;AAEnD,SAAS,SAAS,CAAC,OAAqB;IAGtC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAU,CAAA;IACxC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IAE5B,OAAO,KAAK,CAAA;AACd,CAAC;AAMD,MAAM,UAAU,UAAU,CACxB,OAAO,GAAoC,EAAE;IAE7C,OAAO,SAAS,CAAC;QACf,aAAa,EAAE,YAAY;QAC3B,WAAW,EAAE,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,WAAW;QACzD,YAAY,EAAE,cAAc,CAAC,YAAY;QACzC,MAAM,EAAE,cAAc,CAAC,MAAM;KAC9B,CAAC,CAAA;AACJ,CAAC;AAOD,MAAM,UAAU,OAAO,CACrB,OAAO,GAGH,EAAE;IAEN,OAAO,SAAS,CAAC;QACf,aAAa,EAAE,SAAS;QACxB,WAAW,EAAE,cAAc,CAAC,WAAW;QACvC,YAAY,EAAE,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC,YAAY;QAC1D,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,MAAM;KAChD,CAAC,CAAA;AACJ,CAAC;AAGD,MAAM,UAAU,YAAY,CAAC,KAAY;IACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAEnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAA;IACvE,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAQD,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,OAAO,SAAS,CAAC;QACf,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAA;AACJ,CAAC"}

package/dist/core/data-issue-codes.d.ts

@@ -0,0 +1,3 @@
+import type { IssueCode } from './types.js';
+/** The codes for a filter that is dropped or not valid */
+export declare const DATA_ISSUE_CODES: ReadonlySet<IssueCode>;

package/dist/core/data-issue-codes.js

@@ -0,0 +1,10 @@
+export const DATA_ISSUE_CODES = new Set([
+    'INVALID_PARAM',
+    'INVALID_NUMBER',
+    'INVALID_DATE',
+    'VALUE_TOO_LONG',
+    'INVALID_GROUPED',
+    'TYPE_MISMATCH',
+    'INVALID_URL'
+]);
+//# sourceMappingURL=data-issue-codes.js.map

package/dist/core/data-issue-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-issue-codes.js","sourceRoot":"","sources":["../../src/core/data-issue-codes.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,gBAAgB,GAA2B,IAAI,GAAG,CAAY;IACzE,eAAe;IACf,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,aAAa;CACd,CAAC,CAAA"}

package/dist/core/grid-integration.d.ts

@@ -1,14 +1,50 @@
-import type { FilterState, InternalConfig } from './types.js';
-import type { GridApi } from 'ag-grid-community';
+import type { AGGridUrlSyncConfig, FilterState, InternalConfig } from './types.js';
+import type { FilterModel, GridApi } from 'ag-grid-community';
 /**
  * Detects the expected filter type for a column based on AG Grid configuration
  */
 export declare function detectColumnFilterType(gridApi: GridApi, columnId: string): 'text' | 'number' | 'date';
+/**
+ * Gets the current filter model from AG Grid as a filter state. Filter types
+ * that the library does not support are skipped, and a filter that is not
+ * valid is reported through `options.onParseError`.
+ *
+ * @param gridApi - AG Grid API instance
+ * @param options - Optional options. Only `onParseError` is read.
+ */
+export declare function getFilterModel(gridApi: GridApi, options?: AGGridUrlSyncConfig): FilterState;
 /**
  * Gets the current filter model from AG Grid
+ *
+ * @deprecated Give the grid API as an argument:
+ * `getFilterModel(gridApi, options)`. This form will be removed in 0.6.0.
  */
 export declare function getFilterModel(config: InternalConfig): FilterState;
+/**
+ * Converts an AG Grid filter model to URL filters. It does not call the grid.
+ * Filter types that the library does not support (set, multi) are skipped.
+ */
+export declare function fromGridModel(model: FilterModel | null | undefined, options?: AGGridUrlSyncConfig): FilterState;
+/**
+ * Applies a filter state to AG Grid. A filter whose type does not match the
+ * column is skipped with a warning. An error from the grid is reported
+ * through `options.onParseError`.
+ *
+ * @param filterState - Filter state to apply
+ * @param gridApi - AG Grid API instance
+ * @param options - Optional options. Only `onParseError` is read.
+ */
+export declare function applyFilterModel(filterState: FilterState, gridApi: GridApi, options?: AGGridUrlSyncConfig): void;
 /**
  * Applies a filter state to AG Grid
+ *
+ * @deprecated Give the grid API as an argument:
+ * `applyFilterModel(filterState, gridApi, options)`. This form will be
+ * removed in 0.6.0.
  */
 export declare function applyFilterModel(filterState: FilterState, config: InternalConfig): void;
+/**
+ * Converts URL filters to the AG Grid filter model that `applyFilterModel`
+ * would write. It does not call `setFilterModel`.
+ */
+export declare function toGridModel(filterState: FilterState, gridApi: GridApi, options?: AGGridUrlSyncConfig): FilterModel;

package/dist/core/grid-integration.js

@@ -1,17 +1,26 @@
-import { AG_GRID_OPERATION_NAMES, REVERSE_AG_GRID_OPERATION_NAMES, TEXT_FILTER_OPERATIONS, NUMBER_FILTER_OPERATIONS, DATE_FILTER_OPERATIONS } from './types.js';
-const AG_GRID_TO_NUMBER_OPERATION_MAP = {
-    lessThan: 'lessThan',
-    lessThanOrEqual: 'lessThanOrEqual',
-    greaterThan: 'greaterThan',
-    greaterThanOrEqual: 'greaterThanOrEqual',
-    inRange: 'inRange',
-    equals: 'eq',
-    notEqual: 'notEqual',
-    blank: 'blank',
-    notBlank: 'notBlank'
-};
-function isValidNumberOperation(operation) {
-    return Boolean(operation && operation in AG_GRID_TO_NUMBER_OPERATION_MAP);
+import * as v from 'valibot';
+import { InvalidFilterError, NUMBER_FILTER_OPERATIONS, isDateFilterOperation, isNumberFilterOperation, isTextFilterOperation } from './types.js';
+import { operatorById, operatorFromAgGrid } from './operators.js';
+import { AgGridFilterSchema, JsonObjectSchema } from './schemas.js';
+import { reportIssue, toIssue } from './issues.js';
+import { readNumber } from './validation.js';
+import { resolveOptions } from './options.js';
+function toAgGridOperation(operation) {
+    return operatorById(operation)?.agGrid ?? null;
+}
+function hasGridValue(value) {
+    return value !== undefined && value !== null && String(value).trim() !== '';
+}
+function gridNumber(value, column) {
+    if (!v.is(v.string(), value))
+        return Number(value);
+    const number = readNumber(value);
+    return number instanceof InvalidFilterError
+        ? new InvalidFilterError(`${number.message} (column '${column}')`, undefined, {
+            code: 'INVALID_NUMBER',
+            column
+        })
+        : number;
 }
 function toIsoDateString(val) {
     if (!val)
@@ -19,15 +28,6 @@ function toIsoDateString(val) {
     const match = val.match(/^(\d{4}-\d{2}-\d{2})/);
     return match?.[1] ? match[1] : val || '';
 }
-function isTextFilterOperation(operation) {
-    return TEXT_FILTER_OPERATIONS.includes(operation);
-}
-function isNumberFilterOperation(operation) {
-    return NUMBER_FILTER_OPERATIONS.includes(operation);
-}
-function isDateFilterOperation(operation) {
-    return DATE_FILTER_OPERATIONS.includes(operation);
-}
 export function detectColumnFilterType(gridApi, columnId) {
     try {
         const column = gridApi.getColumn(columnId);
@@ -52,90 +52,126 @@ export function detectColumnFilterType(gridApi, columnId) {
         return 'text';
     }
 }
-export function getFilterModel(config) {
+export function getFilterModel(source, options) {
+    if ('gridApi' in source) {
+        return readGridFilters(source.gridApi, resolveOptions(source));
+    }
+    return readGridFilters(source, resolveOptions(options));
+}
+function readGridFilters(gridApi, options) {
+    let model;
     try {
-        const model = config.gridApi.getFilterModel();
-        const filterState = {};
-        if (!model || typeof model !== 'object') {
-            return filterState;
+        model = gridApi.getFilterModel();
+    }
+    catch (error) {
+        reportIssue(options, toIssue(error, 'GRID_ERROR'));
+        return {};
+    }
+    return fromGridModel(model, options);
+}
+export function fromGridModel(model, options) {
+    const resolved = resolveOptions(options);
+    const filters = new Map();
+    if (!v.is(JsonObjectSchema, model)) {
+        return {};
+    }
+    for (const [column, entry] of Object.entries(model)) {
+        const parsed = v.safeParse(AgGridFilterSchema, entry);
+        if (!parsed.success)
+            continue;
+        const filter = parsed.output;
+        if (filter.filterType === 'text') {
+            const operator = operatorFromAgGrid('text', filter.type);
+            if (operator && isTextFilterOperation(operator.id)) {
+                filters.set(column, {
+                    filterType: 'text',
+                    type: operator.id,
+                    filter: String(filter.filter || '')
+                });
+            }
         }
-        for (const [column, filter] of Object.entries(model)) {
-            if (!filter || typeof filter !== 'object')
+        else if (filter.filterType === 'number') {
+            const operator = operatorFromAgGrid('number', filter.type);
+            const internalOperation = operator?.id;
+            if (!operator ||
+                !internalOperation ||
+                !isNumberFilterOperation(internalOperation)) {
+                reportIssue(resolved, new InvalidFilterError(`Unknown number filter operation '${filter.type}' for column '${column}'. ` +
+                    `Supported operations: ${NUMBER_FILTER_OPERATIONS.map(toAgGridOperation).join(', ')}`, undefined, { code: 'INVALID_PARAM', column }));
                 continue;
-            const { filterType, type, filter: value, filterTo, dateFrom, dateTo } = filter;
-            if (filterType === 'text') {
-                const internalOperation = REVERSE_AG_GRID_OPERATION_NAMES[type];
-                if (internalOperation && isTextFilterOperation(internalOperation)) {
-                    filterState[column] = {
-                        filterType: 'text',
-                        type: internalOperation,
-                        filter: String(value || '')
-                    };
-                }
             }
-            else if (filterType === 'number') {
-                const internalOperation = isValidNumberOperation(type)
-                    ? AG_GRID_TO_NUMBER_OPERATION_MAP[type]
-                    : null;
-                if (!internalOperation) {
-                    if (config.onParseError) {
-                        config.onParseError(new Error(`Unknown number filter operation '${type}' for column '${column}'. ` +
-                            `Supported operations: ${Object.keys(AG_GRID_TO_NUMBER_OPERATION_MAP).join(', ')}`));
-                    }
-                    continue;
+            if (operator.arity === 0) {
+                filters.set(column, {
+                    filterType: 'number',
+                    type: internalOperation,
+                    filter: 0
+                });
+                continue;
+            }
+            if (!hasGridValue(filter.filter) ||
+                (operator.arity === 2 && !hasGridValue(filter.filterTo))) {
+                continue;
+            }
+            const numericValue = gridNumber(filter.filter, column);
+            const numericTo = operator.arity === 2 && hasGridValue(filter.filterTo)
+                ? gridNumber(filter.filterTo, column)
+                : undefined;
+            if (numericValue instanceof InvalidFilterError) {
+                reportIssue(resolved, numericValue);
+                continue;
+            }
+            if (numericTo instanceof InvalidFilterError) {
+                reportIssue(resolved, numericTo);
+                continue;
+            }
+            if (isNaN(numericValue)) {
+                continue;
+            }
+            filters.set(column, internalOperation === 'inRange' && numericTo !== undefined
+                ? {
+                    filterType: 'number',
+                    type: internalOperation,
+                    filter: numericValue,
+                    filterTo: numericTo
                 }
-                if (internalOperation && isNumberFilterOperation(internalOperation)) {
-                    const numericValue = typeof value === 'number' ? value : Number(value);
-                    if (isNaN(numericValue)) {
-                        continue;
-                    }
-                    const numberFilter = {
-                        filterType: 'number',
-                        type: internalOperation,
-                        filter: numericValue
-                    };
-                    if (internalOperation === 'inRange' && typeof filterTo === 'number') {
-                        ;
-                        numberFilter.filterTo = filterTo;
-                    }
-                    filterState[column] = numberFilter;
+                : {
+                    filterType: 'number',
+                    type: internalOperation,
+                    filter: numericValue
+                });
+        }
+        else {
+            const operator = operatorFromAgGrid('date', filter.type);
+            const mappedOperation = operator?.id;
+            if (operator &&
+                mappedOperation &&
+                isDateFilterOperation(mappedOperation)) {
+                if (operator.arity === 0) {
+                    filters.set(column, {
+                        filterType: 'date',
+                        type: mappedOperation,
+                        filter: ''
+                    });
+                    continue;
                 }
-            }
-            else if (filterType === 'date') {
-                const internalOperation = REVERSE_AG_GRID_OPERATION_NAMES[type];
-                let mappedOperation = internalOperation;
-                const AG_GRID_TO_DATE_OPERATION_MAP = {
-                    lessThan: 'dateBefore',
-                    lessThanOrEqual: 'dateBeforeOrEqual',
-                    greaterThan: 'dateAfter',
-                    greaterThanOrEqual: 'dateAfterOrEqual',
-                    inRange: 'dateRange'
-                };
-                mappedOperation = type
-                    ? AG_GRID_TO_DATE_OPERATION_MAP[type] || internalOperation
-                    : internalOperation;
-                if (mappedOperation && isDateFilterOperation(mappedOperation)) {
-                    const dateFilter = {
+                const from = toIsoDateString(filter.dateFrom || String(filter.filter || ''));
+                const to = operator.arity === 2
+                    ? toIsoDateString(filter.dateTo ?? undefined)
+                    : '';
+                if (!from || (operator.arity === 2 && !to))
+                    continue;
+                filters.set(column, operator.arity === 2
+                    ? {
                         filterType: 'date',
                         type: mappedOperation,
-                        filter: toIsoDateString(dateFrom || String(value || ''))
-                    };
-                    if (mappedOperation === 'dateRange' && dateTo) {
-                        ;
-                        dateFilter.filterTo = toIsoDateString(dateTo);
+                        filter: from,
+                        filterTo: to
                     }
-                    filterState[column] = dateFilter;
-                }
+                    : { filterType: 'date', type: mappedOperation, filter: from });
             }
         }
-        return filterState;
-    }
-    catch (error) {
-        if (config.onParseError) {
-            config.onParseError(error);
-        }
-        return {};
     }
+    return Object.fromEntries(filters);
 }
 function convertToAGGridFilter(filter) {
     if (filter.filterType === 'date') {
@@ -155,23 +191,18 @@ function convertToAGGridFilter(filter) {
                 dateTo: null
             };
         }
-        const dateOperationMapping = {
-            dateBefore: 'lessThan',
-            dateBeforeOrEqual: 'lessThanOrEqual',
-            dateAfter: 'greaterThan',
-            dateAfterOrEqual: 'greaterThanOrEqual'
-        };
-        const agOperation = dateOperationMapping[filter.type] ||
-            AG_GRID_OPERATION_NAMES[filter.type];
         return {
             filterType: 'date',
-            type: agOperation,
+            type: toAgGridOperation(filter.type),
             dateFrom: filter.filter,
             dateTo: null
         };
     }
     if (filter.filterType === 'number') {
-        const agGridOperation = AG_GRID_OPERATION_NAMES[filter.type];
+        const agGridOperation = toAgGridOperation(filter.type);
+        if (filter.type === 'blank' || filter.type === 'notBlank') {
+            return { filterType: 'number', type: agGridOperation, filter: null };
+        }
         if (filter.type === 'inRange') {
             const baseFilter = {
                 filterType: 'number',
@@ -188,39 +219,49 @@ function convertToAGGridFilter(filter) {
             filter: filter.filter
         };
     }
-    const agGridOperation = AG_GRID_OPERATION_NAMES[filter.type];
+    const agGridOperation = toAgGridOperation(filter.type);
     return {
         filterType: 'text',
         type: agGridOperation,
         filter: filter.filter
     };
 }
-export function applyFilterModel(filterState, config) {
+export function applyFilterModel(filterState, target, options) {
+    if ('gridApi' in target) {
+        writeGridFilters(filterState, target.gridApi, resolveOptions(target));
+        return;
+    }
+    writeGridFilters(filterState, target, resolveOptions(options));
+}
+function writeGridFilters(filterState, gridApi, options) {
+    const model = toGridModel(filterState, gridApi, options);
     try {
-        const model = {};
-        for (const [column, filter] of Object.entries(filterState)) {
-            if (!filter || typeof filter !== 'object')
-                continue;
-            const expectedType = detectColumnFilterType(config.gridApi, column);
-            if (filter.filterType === 'date' && expectedType !== 'date') {
-                console.warn(`Column '${column}' expects a ${expectedType} filter but received a date filter. This may indicate a configuration mismatch in the column definition or filter application.`);
-                continue;
-            }
-            if (filter.filterType === 'number' && expectedType !== 'number') {
-                console.warn(`Column '${column}' expects a ${expectedType} filter but received a number filter. This may indicate a configuration mismatch in the column definition or filter application.`);
-                continue;
-            }
-            const agGridFilter = convertToAGGridFilter(filter);
-            if (agGridFilter) {
-                model[column] = agGridFilter;
-            }
-        }
-        config.gridApi.setFilterModel(model);
+        gridApi.setFilterModel(model);
     }
     catch (error) {
-        if (config.onParseError) {
-            config.onParseError(error);
+        reportIssue(options, toIssue(error, 'GRID_ERROR'));
+    }
+}
+export function toGridModel(filterState, gridApi, options) {
+    const resolved = resolveOptions(options);
+    const model = new Map();
+    for (const [column, filter] of Object.entries(filterState)) {
+        if (!v.is(JsonObjectSchema, filter))
+            continue;
+        const expectedType = detectColumnFilterType(gridApi, column);
+        if (filter.filterType === 'date' && expectedType !== 'date') {
+            reportIssue(resolved, new InvalidFilterError(`Column '${column}' expects a ${expectedType} filter but received a date filter. This may indicate a configuration mismatch in the column definition or filter application.`, undefined, { code: 'TYPE_MISMATCH', column }));
+            continue;
+        }
+        if (filter.filterType === 'number' && expectedType !== 'number') {
+            reportIssue(resolved, new InvalidFilterError(`Column '${column}' expects a ${expectedType} filter but received a number filter. This may indicate a configuration mismatch in the column definition or filter application.`, undefined, { code: 'TYPE_MISMATCH', column }));
+            continue;
+        }
+        const agGridFilter = convertToAGGridFilter(filter);
+        if (agGridFilter) {
+            model.set(column, agGridFilter);
         }
     }
+    return Object.fromEntries(model);
 }
 //# sourceMappingURL=grid-integration.js.map