Patronum: Effector Operators and Utilities

Common errors

• TypeError: (0, patronum_1.status) is not a function

  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.
  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.

• Error: `patronum` is not compatible with `effector` version X. Expected `^23`.

  cause Your installed `effector` version does not meet the peer dependency requirements of `patronum` (specifically, Patronum v2+ requires Effector v23+).
  fix Update your `effector` package to version `^23` or higher: `npm install effector@^23` or `yarn add effector@^23`.

• TS2345: Argument of type '{ effect: Effect<any, any, any>; }' is not assignable to parameter of type 'object'.

  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.
  fix Upgrade `patronum` to the latest version (e.g., `npm update patronum`). Ensure both `patronum` and `effector` packages are compatible and up-to-date.

• Error: Module not found: Error: Can't resolve 'patronum' in 'path/to/your/file'

  cause The `patronum` package is not correctly installed or resolvable in your project's `node_modules`.
  fix Run `npm install patronum` or `yarn add patronum` to ensure the package is installed. Verify your `node_modules` directory and import paths.

Warnings

• breaking Version 2.0.0 of Patronum introduced a breaking change, requiring Effector version 23 or higher. Older versions of Effector are no longer supported.
  Fix: Ensure your project uses `effector` version `^23` by updating your `package.json` and running `npm install` or `yarn install`.
• gotcha 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.
  Fix: When browsing documentation on patronum.effector.dev or GitHub, ensure you switch to the tag/release matching your installed `patronum` version.
• breaking 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.
  Fix: Refer to the comprehensive migration guide available at `patronum.effector.dev/guides/migration` for detailed steps if upgrading from pre-1.0 versions.
• gotcha 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.
  Fix: Upgrade to `patronum` v2.1.2 or newer to ensure correct type inference and behavior for `interval` with Effector 23's `@@trigger`.
• gotcha 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.
  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.

Install

• npm install patronum npm
• yarn add patronum yarn
• pnpm add patronum pnpm

Imports

• status
  wrong:

  const { status } = require('patronum');

  correct:

  import { status } from 'patronum';

  Patronum primarily uses ES Modules. CommonJS `require` might lead to issues in modern setups.
• debounce
  wrong:

  import debounce from 'patronum';

  correct:

  import { debounce } from 'patronum';

  All core utilities are named exports; there is no default export.
• combineEvents

  import { combineEvents } from 'patronum';

  Many utilities, including `combineEvents`, were added as shorthands in v2.1.0.
• spread
  wrong:

  import * as patronum from 'patronum'; patronum.spread(...);

  correct:

  import { spread } from 'patronum';

  While `* as` works, explicit named imports are idiomatic and tree-shakeable.

Quickstart

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.

import { createEvent, createEffect, createStore } from 'effector';
import { status, debounce, pending, spread } from 'patronum';

// Example 1: Track effect status
const userLoadFx = createEffect<string, { name: string }, Error>();
const $userLoadStatus = status({ effect: userLoadFx });

userLoadFx.use(async (userId) => {
  console.log(`Loading user ${userId}...`);
  await new Promise(resolve => setTimeout(resolve, 500));
  return { name: `User ${userId}` };
});

$userLoadStatus.watch(s => console.log('User load status:', s));
userLoadFx('1'); // Initiates user loading

// Example 2: Debounce an event for search input
const searchInputChanged = createEvent<string>();
const $searchTerm = createStore('');

// Debounce the search input event by 300ms
const debouncedSearch = debounce({
  source: searchInputChanged,
  timeout: 300
});

debouncedSearch.watch(term => console.log('Debounced search term:', term));

searchInputChanged('a');
setTimeout(() => searchInputChanged('ab'), 100);
setTimeout(() => searchInputChanged('abc'), 200); // Only 'abc' will be logged after 300ms from its last call