ag-grid-url-sync 0.4.1 → 0.5.1

package/README.md

@@ -195,38 +195,56 @@ import type {
 
 ```typescript
 import { parseUrlFilters } from 'ag-grid-url-sync/url-parser'
-import { DEFAULT_CONFIG } from 'ag-grid-url-sync/validation'
 import type { FilterState } from 'ag-grid-url-sync/types'
 
 function getFiltersFromUrl(url: string): FilterState {
-  const config = {
-    gridApi: null, // Not needed for parsing
-    ...DEFAULT_CONFIG,
+  // Options that you leave out get their defaults. No grid is needed.
+  return parseUrlFilters(url, {
     onParseError: error => console.error('Parse error:', error)
-  }
-
-  return parseUrlFilters(url, config)
+  })
 }
 ```
 
+`parseUrlFilters` reads the input with these rules, in this order:
+
+| #   | Input                       | Result                   | Example                                   |
+| --- | --------------------------- | ------------------------ | ----------------------------------------- |
+| 1   | A host with no scheme       | Throws `InvalidURLError` | `example.com?…`, `localhost:3000?…`       |
+| 2   | Starts with a scheme        | Absolute URL             | `https://example.com/users?f_name_eq=bob` |
+| 3   | Starts with `/`, `?` or `#` | Relative URL             | `/users?f_name_eq=bob`, `?f_name_eq=bob`  |
+| 4   | Anything else               | Raw query string         | `f_name_eq=bob`                           |
+
+- A relative path must start with `/`. `users?f_name_eq=bob` matches rule 4, so it gives no filters.
+- A bare `localhost?…` with no port cannot be told apart from a raw query, so it matches rule 4.
+- In a raw query string, a `?` or `#` is part of a param name or value.
+
+`InvalidURLError` is thrown for rule 1, and for any input that the `URL` constructor rejects under rules 2 and 3 (for example `http://` or `//[`). A param that is not valid is skipped and sent to `onParseError`.
+
 #### Example: Custom URL Generator
 
 ```typescript
-import { generateUrl, serializeFilters } from 'ag-grid-url-sync/url-generator'
+import { generateUrl } from 'ag-grid-url-sync/url-generator'
 import type { FilterState } from 'ag-grid-url-sync/types'
 
 function createShareableUrl(filters: FilterState, baseUrl: string): string {
-  const config = {
-    gridApi: null, // Not needed for generation
-    paramPrefix: 'f_',
-    maxValueLength: 200,
-    onParseError: () => {}
-  }
-
-  return generateUrl(baseUrl, filters, config)
+  return generateUrl(baseUrl, filters, { maxValueLength: 500 })
 }
 ```
 
+#### Example: Read and Write the Grid Filters
+
+```typescript
+import {
+  getFilterModel,
+  applyFilterModel
+} from 'ag-grid-url-sync/grid-integration'
+
+const filters = getFilterModel(gridApi, { onParseError: console.warn })
+applyFilterModel(filters, otherGridApi)
+```
+
+The config form (`getFilterModel({ ...DEFAULT_CONFIG, gridApi })`) still works, but it is deprecated.
+
 **💡 Pro Tip**: Use granular imports in libraries and applications where bundle size matters. All existing import patterns remain fully supported for backward compatibility.
 
 ### Basic Example
@@ -300,6 +318,10 @@ interface AGGridUrlSyncConfig {
 }
 ```
 
+When the library reads a URL, it reads only the `groupedParam` name and decodes it with the configured `format`. It does not guess the format. This works in both modes, so a grouped link opens in an app in individual mode when the name and format match. If the param is present and not empty, the prefixed params are not read.
+
+> **Note:** A URL written with a different `groupedParam` or `format` does not decode. If you change either option, links that were shared before the change stop working.
+
 ### Format Options
 
 #### QueryString Format (Default)
@@ -418,28 +440,82 @@ import {
 
 ---
 
-### Error Handling for Grouped Serialization
+### Error Handling
 
-You can provide a custom error handler to gracefully handle malformed grouped parameters or serialization errors. The library will throw an `InvalidSerializationError` for invalid formats:
+The library never writes to the console. Each problem goes to one callback, and each error that the library makes has a `code` that you can switch on:
+
+| Code                                                          | Meaning                                                        | Callback                                                                                                 |
+| ------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `INVALID_PARAM`                                               | A param name that is not valid, or an unknown operation        | `onParseError`                                                                                           |
+| `INVALID_NUMBER`                                              | A value that is not a number, or that would be rounded         | `onParseError`                                                                                           |
+| `INVALID_DATE`                                                | A date that does not exist, or a date range in the wrong order | `onParseError`                                                                                           |
+| `VALUE_TOO_LONG`                                              | A text value over `maxValueLength`                             | `onParseError`                                                                                           |
+| `INVALID_GROUPED`                                             | A grouped value that does not decode (bad JSON or base64)      | `onParseError`                                                                                           |
+| `TYPE_MISMATCH`                                               | A number or date filter on a column of another type            | `onParseError`                                                                                           |
+| `INVALID_URL`                                                 | A URL that the parser cannot read                              | Thrown by `parseUrlFilters` and `applyFromUrl`. The React hook catches it and sends it to `onParseError` |
+| `GRID_ERROR`                                                  | The AG Grid API threw                                          | `onParseError` in the core, `onError` in the React hook                                                  |
+| `NOT_READY`                                                   | A hook operation called before the grid is ready               | `onError` (React)                                                                                        |
+| `VIEW_NOT_FOUND`, `VIEW_NAME_REQUIRED`                        | A saved view operation that cannot run                         | `onError` (React)                                                                                        |
+| `STORAGE_UNAVAILABLE`, `STORAGE_FULL`, `STORAGE_WRITE_FAILED` | Browser storage for saved views failed                         | `onError` (React)                                                                                        |
+
+The codes in the first seven rows are data issues: a filter that is dropped or is not valid. The library skips that filter and keeps the others. When the library knows the column, it is in `error.column`. `onParseError` is typed with `Error`, so check `instanceof URLSyncError` before you read `code` or `column`.
+
+Every error is a `URLSyncError`. The classes from earlier versions (`InvalidFilterError`, `InvalidDateError`, `InvalidURLError`, `InvalidSerializationError`) are subclasses of it, so an `instanceof` check still works.
 
 ```typescript
-import { InvalidSerializationError } from 'ag-grid-url-sync/types'
+import { createUrlSync, URLSyncError } from 'ag-grid-url-sync'
 
 const urlSync = createUrlSync(gridApi, {
-  serialization: 'grouped',
-  format: 'json',
   onParseError: error => {
-    if (error instanceof InvalidSerializationError) {
-      // Handle grouped serialization error
-      alert('Invalid filter data in URL!')
-    } else {
-      // Handle other errors
-      console.error(error)
+    if (error instanceof URLSyncError && error.code === 'VALUE_TOO_LONG') {
+      showToast(`The link leaves out the filter on ${error.column}`)
     }
   }
 })
 ```
 
+In grouped mode, an error that comes from the grouped URL value is an `InvalidSerializationError`, and the original error is in `error.cause`. When the original error is an issue with one filter (for example a value over `maxValueLength`), the wrapper has the same `code` and `column`. So a check on `error.code` works the same in both modes. `INVALID_GROUPED` means that the grouped value itself does not decode.
+
+In every grouped format (`querystring`, `json`, `base64`), a text value over `maxValueLength` (default 200) is dropped and reported through `onParseError`, both when the URL is generated and when it is parsed.
+
+#### Dropped Filters in the Result
+
+A caller does not need a callback to see dropped filters. `getUrlState()` and the apply methods return the issues of each call. They are the same objects that `onParseError` gets.
+
+```typescript
+const { url, hasFilters, issues } = urlSync.getUrlState()
+
+if (issues.length > 0) {
+  // The link leaves out these filters, so the recipient sees other rows
+  showToast(`The link leaves out ${issues.length} filter(s)`)
+}
+
+const { issues: urlIssues } = urlSync.applyFromUrl()
+```
+
+In React, the hook returns `issues`: the issues of the latest URL apply (`applyUrlFilters`, `applyFilters`, auto-apply), followed by the issues of the latest URL write. The apply issues stay until the next apply, `clearFilters` or `loadView`. Operation failures (`onError`) are not in the list:
+
+```tsx
+const { shareUrl, issues } = useAGGridUrlSync(gridApi)
+
+return issues.length > 0 ? (
+  <Warning>The link leaves out a filter</Warning>
+) : null
+```
+
+#### `throwOnError`
+
+Like TanStack Query, the library can throw an issue instead of reporting it. Set `throwOnError: true` to throw every issue, or give a function that picks issues. In the core, a thrown issue does not go to `onParseError`, and the first one stops the call. In React, the hook keeps reporting each issue to `onParseError` one time, and then throws the picked issue during render, so an error boundary catches it. The default is `false`.
+
+The library does not change the address bar. Before an error boundary resets, remove the bad param from the URL (or the filter from the grid), or the same issue is thrown again.
+
+```tsx
+useAGGridUrlSync(gridApi, {
+  // Throw only when a link would leave out a filter
+  throwOnError: issue => issue.code === 'VALUE_TOO_LONG'
+})
+```
+
 ### Exports
 
 The package supports granular subpath exports for advanced usage and optimal bundle size:
@@ -558,6 +634,7 @@ const {
   isReady,
   currentUrl,
   hasFilters,
+  issues,
   parseUrlFilters,
   applyFilters,
   getFiltersAsFormat,
@@ -573,11 +650,12 @@ interface UseAGGridUrlSyncOptions {
   paramPrefix?: string // Default: 'f_'
   maxValueLength?: number // Default: 200
   onParseError?: (error: Error) => void
+  throwOnError?: boolean | ((issue: URLSyncError) => boolean) // Default: false
 
   // React-specific options
   autoApplyOnMount?: boolean // Default: false
   enabledWhenReady?: boolean // Default: true
-  onError?: (error: Error, context: string) => void // Advanced error handling
+  onError?: (error: Error, context: string) => void // Operation failures (see Error Handling)
 
   // Saved views: setting a key enables the feature and namespaces its storage
   storageKey?: string // Default: undefined (saved views disabled)
@@ -586,19 +664,20 @@ interface UseAGGridUrlSyncOptions {
 
 #### Hook Return Values
 
-| Property             | Type                             | Description                                     |
-| -------------------- | -------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
-| `shareUrl`           | `(baseUrl?: string) => string`   | Generate shareable URL with current filters     |
-| `getQueryParams`     | `() => string`                   | Get filter state as query parameters            |
-| `applyUrlFilters`    | `(url?: string) => void`         | Apply filters from URL to grid                  |
-| `clearFilters`       | `() => void`                     | Clear all text filters                          |
-| `isReady`            | `boolean`                        | Whether grid API is available and hook is ready |
-| `currentUrl`         | `string`                         | Current URL with filters applied                |
-| `hasFilters`         | `boolean`                        | Whether grid has any active text filters        |
-| `parseUrlFilters`    | `(url: string) => FilterState`   | Parse filters from URL without applying         |
-| `applyFilters`       | `(filters: FilterState) => void` | Apply filter state object to grid               |
-| `getFiltersAsFormat` | `(format: 'querystring'          | 'json'                                          | 'base64') => string`                                       | Serialize filters to any supported format (for sharing/export) |
-| `getCurrentFormat`   | `() => 'individual'              | 'grouped'`                                      | Get the current serialization mode (individual or grouped) |
+| Property             | Type                                                      | Description                                                                 |
+| -------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `shareUrl`           | `(baseUrl?: string) => string`                            | Generate shareable URL with current filters                                 |
+| `getQueryParams`     | `() => string`                                            | Get filter state as query parameters                                        |
+| `applyUrlFilters`    | `(url?: string) => void`                                  | Apply filters from URL to grid                                              |
+| `clearFilters`       | `() => void`                                              | Clear all text filters                                                      |
+| `isReady`            | `boolean`                                                 | Whether grid API is available and hook is ready                             |
+| `currentUrl`         | `string`                                                  | Current URL with filters applied                                            |
+| `hasFilters`         | `boolean`                                                 | Whether the grid has supported filters                                      |
+| `issues`             | `readonly URLSyncError[]`                                 | Filters that the latest URL apply or URL write dropped (see Error Handling) |
+| `parseUrlFilters`    | `(url: string) => FilterState`                            | Parse filters from URL without applying                                     |
+| `applyFilters`       | `(filters: FilterState) => void`                          | Apply filter state object to grid                                           |
+| `getFiltersAsFormat` | `(format: 'querystring' \| 'json' \| 'base64') => string` | Serialize filters to any supported format (for sharing/export)              |
+| `getCurrentFormat`   | `() => 'individual' \| 'grouped'`                         | Get the current serialization mode (individual or grouped)                  |
 
 Saved views (inert unless `storageKey` is set):
 
@@ -692,8 +771,9 @@ store.saveView('Engineering', gridApi.getFilterModel())
 - **🔄 Automatic State Management**: Tracks grid state and filter changes automatically
 - **⚡ Ready State**: `isReady` indicates when the grid API is available
 - **🎯 Auto-Apply**: `autoApplyOnMount` applies URL filters when component mounts.
-  It is attempted once per grid: a failure is reported through `onError` and
-  `onParseError` and is not retried on later renders
+  It is attempted once per grid: a failure is reported one time (a bad filter
+  through `onParseError`, any other failure through `onError`) and is not
+  retried on later renders
 - **🧹 Cleanup**: Automatically cleans up resources when component unmounts
 - **🛡️ Error Boundaries**: Graceful error handling with configurable callbacks
 - **📊 Filter Status**: `hasFilters` tracks whether any filters are active
@@ -889,6 +969,17 @@ const url = urlSync.generateUrl('https://app.com/page')
 // https://app.com/page?f_name_contains=john
 ```
 
+##### `getUrlState(baseUrl?: string): { url: string; hasFilters: boolean; issues: readonly URLSyncError[] }`
+
+Generates the same URL as `generateUrl`, and tells if the grid has filters that the library supports. It reads the grid one time for both values. `hasFilters` comes from the filter state, not from the URL, because the URL also keeps the page's own params.
+
+```typescript
+const { url, hasFilters } = urlSync.getUrlState('https://app.com/page?tab=1')
+// url: https://app.com/page?tab=1 (no filters), hasFilters: false
+```
+
+`issues` holds the filters that this call dropped, for example a text value over `maxValueLength`.
+
 ##### `getQueryParams(): string`
 
 Gets the current filter state as URL query parameters.
@@ -898,17 +989,17 @@ const params = urlSync.getQueryParams()
 // ?f_name_contains=john
 ```
 
-##### `applyFromUrl(url?: string): void`
+##### `applyFromUrl(url?: string): { issues: readonly URLSyncError[] }`
 
-Applies filters from a URL to the grid.
+Applies filters from a URL to the grid, and returns the filters in the URL that were dropped.
 
 ```typescript
 urlSync.applyFromUrl('https://app.com/page?f_name_contains=john')
 ```
 
-##### `applyFilters(filterState: FilterState): void`
+##### `applyFilters(filterState: FilterState): { issues: readonly URLSyncError[] }`
 
-Applies a filter state object to the grid.
+Applies a filter state object to the grid, and returns the filters that were dropped (for example a number filter on a text column).
 
 ```typescript
 urlSync.applyFilters({
@@ -920,7 +1011,7 @@ urlSync.applyFilters({
 })
 ```
 
-##### `clearFilters(): void`
+##### `clearFilters(): { issues: readonly URLSyncError[] }`
 
 Clears all text filters from the grid.
 
@@ -954,8 +1045,10 @@ interface AGGridUrlSyncConfig {
   // Parameter name for grouped mode (default: 'grid_filters')
   groupedParam?: string
 
-  // Prefix for URL parameters (default: 'f_')
-  // In grouped mode, this affects individual parameter names within the group
+  // Prefix for URL parameters in individual mode (default: 'f_')
+  // A prefix without a trailing '_' gets one ('filter' -> 'filter_name_contains').
+  // An empty prefix means the default. Grouped mode always uses 'f_' inside the
+  // grouped value, so grouped URLs do not change with this option.
   paramPrefix?: string
 
   // Maximum length for filter values (default: 200)

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

@@ -1,10 +1,11 @@
 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
  */
 export declare class AGGridUrlSync {
-    private config;
+    private readonly gridApi;
+    private readonly options;
     /**
      * Creates a new instance of AGGridUrlSync
      * @param gridApi - AG Grid API instance
@@ -17,6 +18,16 @@ export declare class AGGridUrlSync {
      * @returns URL string with filter parameters
      */
     generateUrl(baseUrl?: string): string;
+    /**
+     * Generates a URL with the current filter state, and tells if the grid has
+     * filters that the library supports.
+     *
+     * Reads the grid filter model one time, so an error in it is reported one
+     * time. `hasFilters` comes from the filter state, not from the URL: the URL
+     * also keeps the page's own params (#215).
+     * @param baseUrl - Optional base URL (defaults to current URL)
+     */
+    getUrlState(baseUrl?: string): UrlState;
     /**
      * Gets the current filter state as URL query parameters
      * @returns Query parameter string
@@ -25,17 +36,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
      */

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

@@ -1,21 +1,28 @@
-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 = {}) {
-        this.config = {
-            gridApi,
-            ...DEFAULT_CONFIG,
-            ...config
-        };
+        this.gridApi = gridApi;
+        this.options = resolveOptions(config);
     }
     generateUrl(baseUrl) {
-        const filterState = getFilterModel(this.config);
+        return this.getUrlState(baseUrl).url;
+    }
+    getUrlState(baseUrl) {
+        const { options, issues } = collectIssues(this.options);
+        const filterState = getFilterModel(this.gridApi, options);
         const url = baseUrl ?? window.location.href;
-        return generateUrl(url, filterState, this.config);
+        return {
+            url: generateUrl(url, filterState, options),
+            hasFilters: Object.keys(filterState).length > 0,
+            issues
+        };
     }
     getQueryParams() {
         const url = this.generateUrl();
@@ -23,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;QAC5D,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO;YACP,GAAG,cAAc;YACjB,GAAG,MAAM;SACV,CAAA;IACH,CAAC;IAOD,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,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACnD,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":"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"}

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

@@ -1,14 +1,40 @@
-import type { FilterState, InternalConfig } from './types.js';
+import type { AGGridUrlSyncConfig, FilterState, InternalConfig } from './types.js';
 import type { 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;
+/**
+ * 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;