ag-grid-url-sync 0.1.1

package/README.md

@@ -0,0 +1,248 @@
+![CI](https://github.com/nearform/ag-grid-url-sync/actions/workflows/ci.yml/badge.svg?event=push)
+
+# AG Grid URL Sync
+
+A lightweight TypeScript library for synchronizing AG Grid text filters with URL parameters, enabling shareable filter states through clean, human-readable URLs.
+
+## Features
+
+- 🔍 Text filter synchronization (`contains` and `equals` operations)
+- 🔗 Manual URL generation for sharing filter states
+- ↔️ Bidirectional sync between grid and URL
+- 🛠️ Framework agnostic - works with any AG Grid setup
+- 📝 Full TypeScript support with strict mode compliance
+- 🚦 Graceful error handling with configurable error callbacks
+- 🧹 Clean, human-readable URL format
+- ⚡ High performance - handles 100+ filters efficiently (<20ms)
+- 🔧 Configurable URL prefixes for multi-grid scenarios
+- 🛡️ Robust edge case handling (special characters, malformed URLs)
+- 📦 Lightweight bundle size (~3KB gzipped)
+
+## Installation
+
+```bash
+npm install ag-grid-url-sync
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { createUrlSync } from 'ag-grid-url-sync'
+
+// Initialize with AG Grid API
+const urlSync = createUrlSync(gridApi)
+
+// Generate shareable URL with current filters
+const shareableUrl = urlSync.generateUrl()
+
+// Apply filters from URL
+urlSync.applyFromUrl()
+
+// Clear all text filters
+urlSync.clearFilters()
+```
+
+### React Integration
+
+```tsx
+import { createUrlSync } from 'ag-grid-url-sync'
+import { useCallback, useMemo } from 'react'
+
+function useGridUrlSync(gridApi) {
+  const urlSync = useMemo(
+    () => (gridApi ? createUrlSync(gridApi) : null),
+    [gridApi]
+  )
+
+  const shareUrl = useCallback(() => urlSync?.generateUrl() || '', [urlSync])
+
+  const applyUrlFilters = useCallback(() => urlSync?.applyFromUrl(), [urlSync])
+
+  return { shareUrl, applyUrlFilters }
+}
+
+// In your component
+function GridComponent() {
+  const { shareUrl, applyUrlFilters } = useGridUrlSync(gridApi)
+
+  return (
+    <div>
+      <button
+        onClick={() => {
+          const url = shareUrl()
+          navigator.clipboard.writeText(url)
+        }}
+      >
+        Share Filters
+      </button>
+      <button onClick={applyUrlFilters}>Apply URL Filters</button>
+    </div>
+  )
+}
+```
+
+### URL Format
+
+The library generates clean, human-readable URLs:
+
+```
+Base URL: https://app.com/page
+With filters: https://app.com/page?f_name_contains=john&f_status_eq=active
+```
+
+Parameter structure:
+
+- Prefix: `f_` (configurable - useful for multi-grid scenarios)
+- Format: `f_{columnName}_{operation}={value}`
+- Operations: `contains`, `eq` (equals)
+- Standard URL encoding for special characters
+- Supports column names with underscores (e.g., `user_id`, `created_date`)
+
+## API Reference
+
+### `createUrlSync(gridApi, config?)`
+
+Factory function to create a new AGGridUrlSync instance.
+
+```typescript
+import { createUrlSync } from 'ag-grid-url-sync'
+
+const urlSync = createUrlSync(gridApi, {
+  paramPrefix: 'f_', // Default: 'f_'
+  maxValueLength: 200, // Default: 200
+  onParseError: err => console.warn(err)
+})
+```
+
+### `AGGridUrlSync` Class
+
+#### Constructor
+
+```typescript
+new AGGridUrlSync(gridApi: GridApi, config?: AGGridUrlSyncConfig)
+```
+
+#### Methods
+
+##### `generateUrl(baseUrl?: string): string`
+
+Generates a URL with the current filter state.
+
+```typescript
+const url = urlSync.generateUrl('https://app.com/page')
+// https://app.com/page?f_name_contains=john
+```
+
+##### `getQueryParams(): string`
+
+Gets the current filter state as URL query parameters.
+
+```typescript
+const params = urlSync.getQueryParams()
+// ?f_name_contains=john
+```
+
+##### `applyFromUrl(url?: string): void`
+
+Applies filters from a URL to the grid.
+
+```typescript
+urlSync.applyFromUrl('https://app.com/page?f_name_contains=john')
+```
+
+##### `applyFilters(filterState: FilterState): void`
+
+Applies a filter state object to the grid.
+
+```typescript
+urlSync.applyFilters({
+  name: {
+    filterType: 'text',
+    type: 'contains',
+    filter: 'john'
+  }
+})
+```
+
+##### `clearFilters(): void`
+
+Clears all text filters from the grid.
+
+```typescript
+urlSync.clearFilters()
+```
+
+##### `destroy(): void`
+
+Cleans up any resources or event listeners.
+
+```typescript
+urlSync.destroy()
+```
+
+### Configuration
+
+```typescript
+interface AGGridUrlSyncConfig {
+  // Prefix for URL parameters (default: 'f_')
+  // Useful for multi-grid scenarios: 'emp_', 'proj_', etc.
+  paramPrefix?: string
+
+  // Maximum length for filter values (default: 200)
+  maxValueLength?: number
+
+  // Optional error handler for parsing errors
+  // Called when URLs contain invalid filter parameters
+  onParseError?: (error: Error) => void
+}
+```
+
+## Examples
+
+Check out the [examples](./examples) directory for comprehensive working demos:
+
+### 📝 [Basic Example](./examples/basic-example.html)
+
+Simple HTML/JS implementation showing core functionality:
+
+- Initialize URL sync with AG Grid
+- Generate shareable URLs
+- Apply filters from URLs
+- Handle filter changes
+
+### 🚀 [Advanced Demo](./examples/advanced-demo.html)
+
+Feature-rich demonstration including:
+
+- Performance monitoring and benchmarks
+- Multiple filter scenarios (Sales, Engineering, Executive views)
+- URL sharing workflow with copy/email/Slack functionality
+- Error testing with malformed URLs and invalid filters
+- Memory and stress testing capabilities
+
+### 🔗 [Multi-Grid Demo](./examples/multi-grid-demo.html)
+
+Complex example with multiple independent grids:
+
+- Four separate grids (Employees, Projects, Departments, Metrics)
+- Individual URL namespacing with different prefixes
+- Combined URL generation merging all grid states
+- Independent grid controls and clearing functions
+
+All examples work out-of-the-box by opening the HTML files in your browser.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
+
+[![banner](https://raw.githubusercontent.com/nearform/.github/refs/heads/master/assets/os-banner-green.svg)](https://www.nearform.com/contact/?utm_source=open-source&utm_medium=banner&utm_campaign=os-project-pages)

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

@@ -0,0 +1,50 @@
+import type { GridApi } from 'ag-grid-community';
+import type { AGGridUrlSyncConfig, FilterState } from './types.js';
+/**
+ * AGGridUrlSync class for synchronizing AG Grid text filters with URL parameters
+ */
+export declare class AGGridUrlSync {
+    private config;
+    /**
+     * Creates a new instance of AGGridUrlSync
+     * @param gridApi - AG Grid API instance
+     * @param config - Optional configuration options
+     */
+    constructor(gridApi: GridApi, config?: AGGridUrlSyncConfig);
+    /**
+     * Generates a URL with the current filter state
+     * @param baseUrl - Optional base URL (defaults to current URL)
+     * @returns URL string with filter parameters
+     */
+    generateUrl(baseUrl?: string): string;
+    /**
+     * Gets the current filter state as URL query parameters
+     * @returns Query parameter string
+     */
+    getQueryParams(): string;
+    /**
+     * Applies filters from a URL to the grid
+     * @param url - Optional URL to parse (defaults to current URL)
+     */
+    applyFromUrl(url?: string): void;
+    /**
+     * Applies a filter state object to the grid
+     * @param filterState - Filter state to apply
+     */
+    applyFilters(filterState: FilterState): void;
+    /**
+     * Clears all text filters from the grid
+     */
+    clearFilters(): void;
+    /**
+     * Cleans up any resources or event listeners
+     */
+    destroy(): void;
+}
+/**
+ * Factory function to create a new AGGridUrlSync instance
+ * @param gridApi - AG Grid API instance
+ * @param config - Optional configuration options
+ * @returns AGGridUrlSync instance
+ */
+export declare function createUrlSync(gridApi: GridApi, config?: AGGridUrlSyncConfig): AGGridUrlSync;

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

@@ -0,0 +1,78 @@
+import { DEFAULT_CONFIG } from './utils.js';
+import { parseUrlFilters, generateUrl, getFilterModel, applyFilterModel } from './utils.js';
+/**
+ * AGGridUrlSync class for synchronizing AG Grid text filters with URL parameters
+ */
+export class AGGridUrlSync {
+    config;
+    /**
+     * Creates a new instance of AGGridUrlSync
+     * @param gridApi - AG Grid API instance
+     * @param config - Optional configuration options
+     */
+    constructor(gridApi, config = {}) {
+        this.config = {
+            gridApi,
+            paramPrefix: config.paramPrefix ?? DEFAULT_CONFIG.paramPrefix,
+            maxValueLength: config.maxValueLength ?? DEFAULT_CONFIG.maxValueLength,
+            onParseError: config.onParseError ?? (() => { })
+        };
+    }
+    /**
+     * Generates a URL with the current filter state
+     * @param baseUrl - Optional base URL (defaults to current URL)
+     * @returns URL string with filter parameters
+     */
+    generateUrl(baseUrl) {
+        const filterState = getFilterModel(this.config);
+        const url = baseUrl ?? window.location.href;
+        return generateUrl(url, filterState, this.config);
+    }
+    /**
+     * Gets the current filter state as URL query parameters
+     * @returns Query parameter string
+     */
+    getQueryParams() {
+        const url = this.generateUrl();
+        const urlObj = new URL(url);
+        return urlObj.search;
+    }
+    /**
+     * Applies filters from a URL to the grid
+     * @param url - Optional URL to parse (defaults to current URL)
+     */
+    applyFromUrl(url) {
+        const urlToParse = url ?? window.location.href;
+        const filterState = parseUrlFilters(urlToParse, this.config);
+        this.applyFilters(filterState);
+    }
+    /**
+     * Applies a filter state object to the grid
+     * @param filterState - Filter state to apply
+     */
+    applyFilters(filterState) {
+        applyFilterModel(filterState, this.config);
+    }
+    /**
+     * Clears all text filters from the grid
+     */
+    clearFilters() {
+        this.applyFilters({});
+    }
+    /**
+     * Cleans up any resources or event listeners
+     */
+    destroy() {
+        // Currently no cleanup needed, but included for future use
+    }
+}
+/**
+ * Factory function to create a new AGGridUrlSync instance
+ * @param gridApi - AG Grid API instance
+ * @param config - Optional configuration options
+ * @returns AGGridUrlSync instance
+ */
+export function createUrlSync(gridApi, config) {
+    return new AGGridUrlSync(gridApi, config);
+}
+//# sourceMappingURL=ag-grid-url-sync.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ag-grid-url-sync.js","sourceRoot":"","sources":["../src/ag-grid-url-sync.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EACL,eAAe,EACf,WAAW,EACX,cAAc,EACd,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,CAAgB;IAE9B;;;;OAIG;IACH,YAAY,OAAgB,EAAE,SAA8B,EAAE;QAC5D,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO;YACP,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,cAAc,CAAC,WAAW;YAC7D,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,cAAc,CAAC,cAAc;YACtE,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;SAChD,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,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;IAED;;;OAGG;IACH,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;IAED;;;OAGG;IACH,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;IAED;;;OAGG;IACH,YAAY,CAAC,WAAwB;QACnC,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAED;;OAEG;IACH,YAAY;QACV,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IACvB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,2DAA2D;IAC7D,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,MAA4B;IAE5B,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AGGridUrlSync, createUrlSync } from './ag-grid-url-sync.js';
+export * from './types.js';
+export { parseUrlFilters, serializeFilters, generateUrl, getFilterModel, applyFilterModel, validateFilterValue, parseFilterParam, DEFAULT_CONFIG } from './utils.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { AGGridUrlSync, createUrlSync } from './ag-grid-url-sync.js';
+export * from './types.js';
+export { parseUrlFilters, serializeFilters, generateUrl, getFilterModel, applyFilterModel, validateFilterValue, parseFilterParam, DEFAULT_CONFIG } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAEpE,cAAc,YAAY,CAAA;AAE1B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+import type { GridApi as AGGridApi } from 'ag-grid-community';
+/**
+ * Configuration options for AG Grid URL Sync
+ */
+export interface AGGridUrlSyncConfig {
+    /**
+     * Prefix for URL parameters. Default: 'f_'
+     */
+    paramPrefix?: string;
+    /**
+     * Maximum length for filter values. Default: 200
+     */
+    maxValueLength?: number;
+    /**
+     * Optional error handler for parsing errors
+     */
+    onParseError?: (error: Error) => void;
+}
+/**
+ * Supported filter operations
+ */
+export type FilterOperation = 'contains' | 'eq';
+/**
+ * Filter state for a single column
+ */
+export interface ColumnFilter {
+    filterType: 'text';
+    type: FilterOperation;
+    filter: string;
+}
+/**
+ * Complete filter state mapping
+ */
+export interface FilterState {
+    [columnId: string]: ColumnFilter;
+}
+/**
+ * Internal configuration with defaults
+ */
+export interface InternalConfig extends Required<AGGridUrlSyncConfig> {
+    gridApi: AGGridApi;
+}
+/**
+ * Error types for URL sync operations
+ */
+export declare class URLSyncError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidFilterError extends URLSyncError {
+    constructor(message: string);
+}
+export declare class InvalidURLError extends URLSyncError {
+    constructor(message: string);
+}
+export type ParsedFilterParam = {
+    columnName: string;
+    operation: 'contains' | 'equals';
+    value: string;
+    action: 'apply' | 'remove';
+};
+export type GridApi = AGGridApi;
+export declare const OPERATION_MAP: {
+    readonly contains: "contains";
+    readonly eq: "equals";
+};
+export declare const REVERSE_OPERATION_MAP: {
+    readonly contains: "contains";
+    readonly equals: "eq";
+};

package/dist/types.js

@@ -0,0 +1,31 @@
+/**
+ * Error types for URL sync operations
+ */
+export class URLSyncError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'URLSyncError';
+    }
+}
+export class InvalidFilterError extends URLSyncError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidFilterError';
+    }
+}
+export class InvalidURLError extends URLSyncError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidURLError';
+    }
+}
+// Internal operation mapping
+export const OPERATION_MAP = {
+    contains: 'contains',
+    eq: 'equals'
+};
+export const REVERSE_OPERATION_MAP = {
+    contains: 'contains',
+    equals: 'eq'
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkDA;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;IAC5B,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAYD,6BAA6B;AAC7B,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,UAAU;IACpB,EAAE,EAAE,QAAQ;CACJ,CAAA;AAEV,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,IAAI;CACJ,CAAA"}

package/dist/utils.d.ts

@@ -0,0 +1,36 @@
+import type { FilterState, ColumnFilter, InternalConfig } from './types.js';
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: {
+    readonly paramPrefix: "f_";
+    readonly maxValueLength: 200;
+};
+/**
+ * Validates a filter value against configuration constraints
+ */
+export declare function validateFilterValue(value: string, config: InternalConfig): string;
+/**
+ * Parses a URL parameter into a column filter
+ */
+export declare function parseFilterParam(param: string, value: string, expectedPrefix?: string): ColumnFilter;
+/**
+ * Converts URL search params into a filter state object
+ */
+export declare function parseUrlFilters(url: string, config: InternalConfig): FilterState;
+/**
+ * Converts a filter state object into URL search parameters
+ */
+export declare function serializeFilters(filterState: FilterState, config: InternalConfig): URLSearchParams;
+/**
+ * Generates a URL with the current filter state
+ */
+export declare function generateUrl(baseUrl: string, filterState: FilterState, config: InternalConfig): string;
+/**
+ * Gets the current filter model from AG Grid
+ */
+export declare function getFilterModel(config: InternalConfig): FilterState;
+/**
+ * Applies a filter state to AG Grid
+ */
+export declare function applyFilterModel(filterState: FilterState, config: InternalConfig): void;

package/dist/utils.js

@@ -0,0 +1,188 @@
+import { InvalidFilterError, InvalidURLError } from './types.js';
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    paramPrefix: 'f_',
+    maxValueLength: 200
+};
+/**
+ * Operation mapping between URL parameters and AG Grid filter types
+ */
+const OPERATION_MAP = {
+    contains: 'contains',
+    eq: 'eq'
+};
+/**
+ * Validates a filter value against configuration constraints
+ */
+export function validateFilterValue(value, config) {
+    if (value.length > config.maxValueLength) {
+        throw new InvalidFilterError(`Filter value exceeds maximum length of ${config.maxValueLength} characters`);
+    }
+    return value;
+}
+/**
+ * Extracts column name and operation from a filter parameter
+ */
+function extractColumnAndOperation(param, expectedPrefix) {
+    const ensureTrailingUnderscore = (prefix) => prefix.endsWith('_') ? prefix : prefix + '_';
+    const sanitizedPrefix = expectedPrefix
+        ? ensureTrailingUnderscore(expectedPrefix)
+        : ensureTrailingUnderscore(DEFAULT_CONFIG.paramPrefix);
+    const prefixToCheck = sanitizedPrefix.slice(0, -1);
+    if (!param.startsWith(prefixToCheck + '_')) {
+        throw new InvalidFilterError(`Invalid filter prefix in parameter: ${param}`);
+    }
+    // Remove prefix and find the last underscore to separate column from operation
+    const withoutPrefix = param.substring(prefixToCheck.length + 1);
+    const lastUnderscoreIndex = withoutPrefix.lastIndexOf('_');
+    if (lastUnderscoreIndex === -1) {
+        throw new InvalidFilterError(`Invalid filter parameter format: ${param}`);
+    }
+    const column = withoutPrefix.substring(0, lastUnderscoreIndex);
+    const operation = withoutPrefix.substring(lastUnderscoreIndex + 1);
+    if (!column.trim()) {
+        throw new InvalidFilterError(`Empty column name in parameter: ${param}`);
+    }
+    return { column, operation };
+}
+/**
+ * Parses a URL parameter into a column filter
+ */
+export function parseFilterParam(param, value, expectedPrefix) {
+    const { operation } = extractColumnAndOperation(param, expectedPrefix);
+    const filterOp = OPERATION_MAP[operation];
+    if (!filterOp) {
+        throw new InvalidFilterError(`Unsupported filter operation: ${operation}`);
+    }
+    return {
+        filterType: 'text',
+        type: filterOp,
+        filter: value || ''
+    };
+}
+/**
+ * Converts URL search params into a filter state object
+ */
+export function parseUrlFilters(url, config) {
+    try {
+        const urlObj = new URL(url);
+        const filterState = {};
+        for (const [param, value] of urlObj.searchParams.entries()) {
+            if (!param.startsWith(config.paramPrefix))
+                continue;
+            try {
+                // Extract column name and parse the filter parameter
+                const { column: columnName } = extractColumnAndOperation(param, config.paramPrefix);
+                const filterParam = parseFilterParam(param, value, config.paramPrefix);
+                const validatedValue = validateFilterValue(value, config);
+                filterState[columnName] = {
+                    ...filterParam,
+                    filter: validatedValue
+                };
+            }
+            catch (err) {
+                if (config.onParseError) {
+                    config.onParseError(err);
+                }
+                // Skip invalid filters but continue processing
+                continue;
+            }
+        }
+        return filterState;
+    }
+    catch (err) {
+        throw new InvalidURLError(`Failed to parse URL: ${err.message}`);
+    }
+}
+/**
+ * Converts a filter state object into URL search parameters
+ */
+export function serializeFilters(filterState, config) {
+    const params = new URLSearchParams();
+    for (const [column, filter] of Object.entries(filterState)) {
+        if (filter.filterType !== 'text')
+            continue;
+        const operation = filter.type === 'contains' ? 'contains' : 'eq';
+        const paramName = `${config.paramPrefix}${column}_${operation}`;
+        const value = validateFilterValue(filter.filter, config);
+        // URLSearchParams already handles encoding, so don't double-encode
+        params.append(paramName, value);
+    }
+    return params;
+}
+/**
+ * Generates a URL with the current filter state
+ */
+export function generateUrl(baseUrl, filterState, config) {
+    const url = new URL(baseUrl);
+    const filterParams = serializeFilters(filterState, config);
+    // Preserve existing non-filter parameters
+    for (const [key, value] of url.searchParams.entries()) {
+        if (!key.startsWith(config.paramPrefix)) {
+            filterParams.append(key, value);
+        }
+    }
+    url.search = filterParams.toString();
+    return url.toString();
+}
+/**
+ * Gets the current filter model from AG Grid
+ */
+export function getFilterModel(config) {
+    try {
+        const model = config.gridApi.getFilterModel();
+        const filterState = {};
+        if (!model || typeof model !== 'object') {
+            return filterState;
+        }
+        for (const [column, filter] of Object.entries(model)) {
+            if (!filter || typeof filter !== 'object')
+                continue;
+            const { filterType, type, filter: value } = filter;
+            if (filterType !== 'text' || !value)
+                continue;
+            if (type === 'contains' || type === 'equals') {
+                filterState[column] = {
+                    filterType: 'text',
+                    type: type === 'equals' ? 'eq' : 'contains',
+                    filter: value
+                };
+            }
+        }
+        return filterState;
+    }
+    catch (error) {
+        if (config.onParseError) {
+            config.onParseError(error);
+        }
+        return {};
+    }
+}
+/**
+ * Applies a filter state to AG Grid
+ */
+export function applyFilterModel(filterState, config) {
+    try {
+        const model = {};
+        for (const [column, filter] of Object.entries(filterState)) {
+            if (filter &&
+                typeof filter === 'object' &&
+                filter.filterType === 'text') {
+                model[column] = {
+                    filterType: filter.filterType,
+                    type: filter.type === 'eq' ? 'equals' : filter.type,
+                    filter: filter.filter
+                };
+            }
+        }
+        config.gridApi.setFilterModel(model);
+    }
+    catch (error) {
+        if (config.onParseError) {
+            config.onParseError(error);
+        }
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "ag-grid-url-sync",
+  "version": "0.1.1",
+  "description": "AG Grid URL Sync - Synchronize AG Grid text filters with URL parameters",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rimraf dist",
+    "compile": "tsc",
+    "build": "npm run clean && npm run compile && npm run validate",
+    "validate": "npm run size-check && npm run type-check",
+    "size-check": "bundlesize",
+    "type-check": "tsc --noEmit --strict",
+    "ci": "npm run build && npm run check-exports && npm run lint && npm run test",
+    "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
+    "prepare": "husky"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nearform/ag-grid-url-state-sync.git"
+  },
+  "keywords": [
+    "ag-grid",
+    "url",
+    "state",
+    "sync",
+    "filter",
+    "share",
+    "typescript"
+  ],
+  "author": "NearForm",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/nearform/ag-grid-url-state-sync/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/nearform/ag-grid-url-state-sync#readme",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/js": "^9.29.0",
+    "@types/jsdom": "^21.1.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "ag-grid-community": "^33.3.2",
+    "bundlesize": "^0.18.2",
+    "eslint": "^9.29.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.5.0",
+    "globals": "^16.2.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "lint-staged": "^16.1.2",
+    "prettier": "^3.6.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "ag-grid-community": ">=28.0.0"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": "eslint --cache --fix"
+  },
+  "bundlesize": [
+    {
+      "path": "./dist/index.js",
+      "maxSize": "5KB"
+    },
+    {
+      "path": "./dist/ag-grid-url-sync.js",
+      "maxSize": "4KB"
+    },
+    {
+      "path": "./dist/utils.js",
+      "maxSize": "4KB"
+    }
+  ]
+}