{"id":11530,"library":"patronum","title":"Patronum: Effector Operators and Utilities","description":"Patronum is a comprehensive utility library designed to extend the core capabilities of the Effector state management framework, providing a rich collection of operators and methods for common reactive programming patterns. It helps Effector developers implement functionality like debouncing, throttling, delays, status tracking for effects, event combination, and store value manipulation with significantly less boilerplate. The current stable version is 2.3.0, and the project exhibits an active development and release cadence, frequently adding new operators and improving existing ones, often with multiple minor and patch releases within a few months. Its key differentiator lies in its deep integration and specialization for the Effector ecosystem, offering purpose-built, type-safe solutions that seamlessly work with Effector's primitive units like Stores, Events, and Effects, fostering modularity and maintainability in complex applications. While it simplifies many common tasks, users must pay attention to its `effector` peer dependency version for compatibility.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/effector/patronum","tags":["javascript","babel-preset","effector","lib","modules","stdlib","util","macro","typescript"],"install":[{"cmd":"npm install patronum","lang":"bash","label":"npm"},{"cmd":"yarn add patronum","lang":"bash","label":"yarn"},{"cmd":"pnpm add patronum","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Patronum is an utility library for Effector and requires it as a peer dependency to function.","package":"effector","optional":false}],"imports":[{"note":"Patronum primarily uses ES Modules. CommonJS `require` might lead to issues in modern setups.","wrong":"const { status } = require('patronum');","symbol":"status","correct":"import { status } from 'patronum';"},{"note":"All core utilities are named exports; there is no default export.","wrong":"import debounce from 'patronum';","symbol":"debounce","correct":"import { debounce } from 'patronum';"},{"note":"Many utilities, including `combineEvents`, were added as shorthands in v2.1.0.","symbol":"combineEvents","correct":"import { combineEvents } from 'patronum';"},{"note":"While `* as` works, explicit named imports are idiomatic and tree-shakeable.","wrong":"import * as patronum from 'patronum'; patronum.spread(...);","symbol":"spread","correct":"import { spread } from 'patronum';"}],"quickstart":{"code":"import { createEvent, createEffect, createStore } from 'effector';\nimport { status, debounce, pending, spread } from 'patronum';\n\n// Example 1: Track effect status\nconst userLoadFx = createEffect<string, { name: string }, Error>();\nconst $userLoadStatus = status({ effect: userLoadFx });\n\nuserLoadFx.use(async (userId) => {\n  console.log(`Loading user ${userId}...`);\n  await new Promise(resolve => setTimeout(resolve, 500));\n  return { name: `User ${userId}` };\n});\n\n$userLoadStatus.watch(s => console.log('User load status:', s));\nuserLoadFx('1'); // Initiates user loading\n\n// Example 2: Debounce an event for search input\nconst searchInputChanged = createEvent<string>();\nconst $searchTerm = createStore('');\n\n// Debounce the search input event by 300ms\nconst debouncedSearch = debounce({\n  source: searchInputChanged,\n  timeout: 300\n});\n\ndebouncedSearch.watch(term => console.log('Debounced search term:', term));\n\nsearchInputChanged('a');\nsetTimeout(() => searchInputChanged('ab'), 100);\nsetTimeout(() => searchInputChanged('abc'), 200); // Only 'abc' will be logged after 300ms from its last call\n","lang":"typescript","description":"This example demonstrates how to use `status` to track the state of an Effector effect and `debounce` to rate-limit an Effector event for use cases like search inputs."},"warnings":[{"fix":"Ensure your project uses `effector` version `^23` by updating your `package.json` and running `npm install` or `yarn install`.","message":"Version 2.0.0 of Patronum introduced a breaking change, requiring Effector version 23 or higher. Older versions of Effector are no longer supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"When browsing documentation on patronum.effector.dev or GitHub, ensure you switch to the tag/release matching your installed `patronum` version.","message":"Patronum's documentation is versioned. Viewing documentation for the latest version while using an older library version can lead to confusion and incorrect API usage. Always refer to the documentation corresponding to your installed Patronum version.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the comprehensive migration guide available at `patronum.effector.dev/guides/migration` for detailed steps if upgrading from pre-1.0 versions.","message":"Older breaking changes occurred during major version bumps from 0.x to 1.x (0.14 to 0.100, 0.100 to 0.110, and 0.110 to 1.0). Users upgrading from very old `0.x` versions should consult the migration guide.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade to `patronum` v2.1.2 or newer to ensure correct type inference and behavior for `interval` with Effector 23's `@@trigger`.","message":"An issue in v2.1.2 fixed incorrect types for `@@trigger` in the `interval` operator since Effector 23. This might affect advanced usages relying on `@@trigger` protocol.","severity":"gotcha","affected_versions":"2.0.0 - 2.1.1"},{"fix":"Update to `patronum` v2.1.1 or higher. Review any code using `status` or `snapshot` results for potential type mismatches if your TypeScript configuration is strict.","message":"Version 2.1.1 included fixes for the return types of `status` and `snapshot` operators, ensuring they correctly return `StoreWritable`. This could cause type errors if your codebase relied on previous, incorrect type inferences.","severity":"gotcha","affected_versions":"<2.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ES Modules (e.g., `\"type\": \"module\"` in `package.json` for Node.js) and use `import { status } from 'patronum';`. If in a mixed environment, check your bundler/transpiler configuration.","cause":"This typically occurs in CommonJS environments trying to `require()` an ESM-only package, or due to incorrect transpilation settings where named ESM exports are not correctly resolved.","error":"TypeError: (0, patronum_1.status) is not a function"},{"fix":"Update your `effector` package to version `^23` or higher: `npm install effector@^23` or `yarn add effector@^23`.","cause":"Your installed `effector` version does not meet the peer dependency requirements of `patronum` (specifically, Patronum v2+ requires Effector v23+).","error":"Error: `patronum` is not compatible with `effector` version X. Expected `^23`."},{"fix":"Upgrade `patronum` to the latest version (e.g., `npm update patronum`). Ensure both `patronum` and `effector` packages are compatible and up-to-date.","cause":"This TypeScript error often points to an outdated `patronum` version where types were incorrect (e.g., `status` return type fix in v2.1.1) or a mismatch between `patronum` and `effector` types.","error":"TS2345: Argument of type '{ effect: Effect<any, any, any>; }' is not assignable to parameter of type 'object'."},{"fix":"Run `npm install patronum` or `yarn add patronum` to ensure the package is installed. Verify your `node_modules` directory and import paths.","cause":"The `patronum` package is not correctly installed or resolvable in your project's `node_modules`.","error":"Error: Module not found: Error: Can't resolve 'patronum' in 'path/to/your/file'"}],"ecosystem":"npm"}