v0.5.0

v0.5.0

What's New

New plain Format

A new human-readable format for cleaner, hand-editable URLs:

import { plain } from 'zustand-querystring/format/plain';

const useStore = create()(
  querystring(
    (set) => ({
      query: "hello",
      filters: { sort: "name" },
      tags: ["a", "b"]
    }),
    {
      key: false,
      format: plain,
      select: () => ({ query: true, filters: true, tags: true }),
    }
  )
);

Result: ?query=hello&filters.sort=name&tags=a&tags=b

Features:

• Dot notation for nested objects: filters.sort=name
• Repeated keys for arrays: tags=a&tags=b
• Fully customizable separators via createFormat()

Limitation: The plain format requires initialState for proper type inference. Since URL params are strings, the format uses your initial state to determine types:

• Arrays are detected from initial state (otherwise multiple values become last-value-wins)
• Numbers, booleans, and dates are auto-parsed, but initialState hints ensure correct types
• Without initialState, values like "123" may be parsed as numbers automatically

Interactive Playground

New live playground to experiment with formats and options:
👉 https://zustand-querystring.nitedani.workers.dev

Improved Escaping

• Escape character changed from / to _ for better URL compatibility
• Smarter escaping: only special characters are escaped, regular underscores stay as-is
• Example: a_b_c stays as a_b_c (not a__b__c)

Breaking Changes

key: false is now the default

The default value of key has changed from 'state' to false.

Before (v0.4.0):

// Default: key: 'state'
// URL: ?state=count%3A5

After (v0.5.0):

// Default: key: false (standalone mode)
// URL: ?count=5

To restore the old behavior, explicitly set key: 'state':

querystring(store, { key: 'state', ... })

Escape character changed

Default escape character changed from / to _ in both marked and plain formats.

readable format renamed to marked

The readable format has been renamed to marked for clarity.

// Before
import { readable } from 'zustand-querystring/format/readable';

// After
import { marked } from 'zustand-querystring/format/marked';

---

Full Changelog: v0.4.0...v0.5.0