nanoeffects 0.20.0 → 0.21.0

package/dist/notrace/policies.d.ts

@@ -9,6 +9,14 @@ type KeyOption<P> = {
    */
   key?: (payload: P) => unknown;
 };
+/** Options of a policy called without a task: `key` is left out. */
+type Unkeyed<O> = Omit<O, "key"> & {
+  key?: undefined;
+};
+/** Options of a policy called without a task, with a `key` that tells the payload type. */
+type Keyed<O, P> = O & {
+  key: (payload: P) => unknown;
+};
 //#endregion
 //#region src/policies/debounce.d.ts
 type DebounceResult<R> = Promise<R | undefined> | Promise<Awaited<R> | undefined> | undefined;
@@ -18,6 +26,10 @@ type DebounceOptions<P = never> = KeyOption<P> & {
   /** Run the last call of a burst after `ms` of quiet. Default `true`. */
   trailing?: boolean;
 };
+/** What `debounce(ms)` returns: it turns a task into a `debounce` task. */
+type DebounceWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, DebounceResult<R>>;
+/** What `debounce(ms, { key })` returns: the payload type comes from `key`. */
+type KeyedDebounceWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, DebounceResult<R>>;
 /**
  * Waits for `ms` of quiet, then runs; a new call restarts the wait and drops
  * the previous. With `leading` the first call of a burst runs at once, and the
@@ -38,14 +50,24 @@ type DebounceOptions<P = never> = KeyOption<P> & {
  * bus.emit("input", "re"); // only the last call runs, 300 ms after it
  * ```
  */
-export declare const debounce: <P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: DebounceOptions<P>) => Task<P, E, DebounceResult<R>>;
+export declare function debounce<P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: DebounceOptions<P>): Task<P, E, DebounceResult<R>>;
+export declare function debounce(ms: number, options?: Unkeyed<DebounceOptions>): DebounceWrapper;
+export declare function debounce<P>(ms: number, options: Keyed<DebounceOptions<P>, P>): KeyedDebounceWrapper<P>;
 //#endregion
 //#region src/policies/latest.d.ts
 type LatestOptions<P = never> = KeyOption<P>;
+type LatestResult<R> = R | Promise<Awaited<R> | undefined> | undefined;
+/** What `latest()` returns: it turns a task into a `latest` task. */
+type LatestWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, LatestResult<R>>;
+/** What `latest({ key })` returns: the payload type comes from `key`. */
+type KeyedLatestWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, LatestResult<R>>;
 /**
  * Aborts the previous run when a new call arrives; stale results are dropped.
  * With `options.key` each key has its own latest run.
  *
+ * Called without the task, `latest()` returns a function that takes the task,
+ * so `usePolicy(callback, latest())` has no `(task) => ...` to get wrong.
+ *
  * @example
  * ```ts
  * bus.on(
@@ -61,12 +83,21 @@ type LatestOptions<P = never> = KeyOption<P>;
  *
  * // one latest run per user instead of one for all
  * bus.on("load", latest(loadUser, { key: (user) => user.id }));
+ *
+ * // without the task: for a hook that builds the task itself
+ * const search = usePolicy(runSearch, latest());
  * ```
  */
-export declare const latest: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LatestOptions<P>) => Task<P, E, R | Promise<Awaited<R> | undefined> | undefined>;
+export declare function latest<P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LatestOptions<P>): Task<P, E, LatestResult<R>>;
+export declare function latest(options?: Unkeyed<LatestOptions>): LatestWrapper;
+export declare function latest<P>(options: Keyed<LatestOptions<P>, P>): KeyedLatestWrapper<P>;
 //#endregion
 //#region src/policies/leading.d.ts
 type LeadingOptions<P = never> = KeyOption<P>;
+/** What `leading()` returns: it turns a task into a `leading` task. */
+type LeadingWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
+/** What `leading({ key })` returns: the payload type comes from `key`. */
+type KeyedLeadingWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
 /**
  * Drops new calls while the task is still running. The lock is released when
  * the run settles or when its task is aborted, whichever comes first, so a
@@ -86,7 +117,9 @@ type LeadingOptions<P = never> = KeyOption<P>;
  * bus.emit("save", draft); // dropped while the first save is in flight
  * ```
  */
-export declare const leading: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LeadingOptions<P>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
+export declare function leading<P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LeadingOptions<P>): Task<P, E, R | Promise<Awaited<R>> | undefined>;
+export declare function leading(options?: Unkeyed<LeadingOptions>): LeadingWrapper;
+export declare function leading<P>(options: Keyed<LeadingOptions<P>, P>): KeyedLeadingWrapper<P>;
 //#endregion
 //#region src/policies/queue.d.ts
 type QueueOptions<P = never> = KeyOption<P> & {
@@ -101,6 +134,10 @@ type QueueOptions<P = never> = KeyOption<P> & {
    */
   overflow?: "drop-new" | "drop-old";
 };
+/** What `queue()` returns: it turns a task into a `queue` task. */
+type QueueWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, Promise<Awaited<R> | undefined>>;
+/** What `queue({ key })` returns: the payload type comes from `key`. */
+type KeyedQueueWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, Promise<Awaited<R> | undefined>>;
 /**
  * Runs calls one after another, in the order they arrived: a call starts when
  * fewer than `concurrency` calls are running. Every call returns a promise with
@@ -131,7 +168,9 @@ type QueueOptions<P = never> = KeyOption<P> & {
  * bus.emit("save", b); // waits for a, then runs
  * ```
  */
-export declare const queue: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: QueueOptions<P>) => Task<P, E, Promise<Awaited<R> | undefined>>;
+export declare function queue<P, E extends EventMap, R>(fn: Task<P, E, R>, options?: QueueOptions<P>): Task<P, E, Promise<Awaited<R> | undefined>>;
+export declare function queue(options?: Unkeyed<QueueOptions>): QueueWrapper;
+export declare function queue<P>(options: Keyed<QueueOptions<P>, P>): KeyedQueueWrapper<P>;
 //#endregion
 //#region src/policies/throttle.d.ts
 type ThrottleOptions<P = never> = KeyOption<P> & {
@@ -140,6 +179,10 @@ type ThrottleOptions<P = never> = KeyOption<P> & {
   /** Run the latest call made while waiting, at the end of the window. Default `true`. */
   trailing?: boolean;
 };
+/** What `throttle(ms)` returns: it turns a task into a `throttle` task. */
+type ThrottleWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<R | undefined> | undefined>;
+/** What `throttle(ms, { key })` returns: the payload type comes from `key`. */
+type KeyedThrottleWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<R | undefined> | undefined>;
 /**
  * At most one run per `ms`, with the semantics of lodash `throttle` (and
  * patronum): a call made when the throttle is idle, that is, at least `ms`
@@ -166,7 +209,9 @@ type ThrottleOptions<P = never> = KeyOption<P> & {
  * bus.emit("scroll", 30); // runs once the 200 ms window closes
  * ```
  */
-export declare const throttle: <P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: ThrottleOptions<P>) => Task<P, E, R | Promise<R | undefined> | undefined>;
+export declare function throttle<P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: ThrottleOptions<P>): Task<P, E, R | Promise<R | undefined> | undefined>;
+export declare function throttle(ms: number, options?: Unkeyed<ThrottleOptions>): ThrottleWrapper;
+export declare function throttle<P>(ms: number, options: Keyed<ThrottleOptions<P>, P>): KeyedThrottleWrapper<P>;
 //#endregion
 //#region src/policies/with-policy.d.ts
 /** What `withPolicy` returns: the task as a plain function that can be cancelled. */

package/dist/notrace/policies.js

@@ -1 +1 @@
-import{a as e,c as t,i as n,n as r,o as i,t as a}from"./context-yYU3_9lq.js";import{n as o,r as s,t as c}from"./delay-BosJKFjg.js";import{n as l,t as u}from"./promise-CSLpzwSR.js";import{n as d,t as f}from"./lifecycle-key-8iX8RUVD.js";const p=e=>Reflect.get(e,f),m=e=>{p(e)?.start()},h=(t,n,r)=>(m(t),e(t,n,r)),g=(e,t)=>{i(e,t,`drop`),p(e)?.drop()},_=(e,t)=>{p(e)?.done(t)},v=(e,t,n)=>{let r=p(e);t?r?.cancel(n):r?.drop()},y=e=>(Reflect.set(e,d,!0),e),b=()=>{},x=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},S=(e,t)=>y(e?x(e,t):t(b)),C=(e,t={})=>S(t.key,t=>w(`latest`,(t,n,r)=>(r(),e(t,n)),t)),w=(e,r,o=b)=>{let s=null;return(c,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=n(u);s=d;let p=a(d,e),h=!1,g=()=>{d.signal.aborted||(h=!0,m(d),i(d,e,`start`))};t(d,e=>{v(d,h,e),p(h?`cancel`:`drop`)});let _=()=>{f(),s===d&&(s=null,o())},y=e=>{if(!d.signal.aborted)return p(h?`done`:`drop`),e};try{let e=r(c,d,g);return l(e)?Promise.resolve(e).then(y,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(_):(_(),y(e))}catch(e){if(_(),d.signal.aborted)return;throw p(`error`,e),e}}},T=(e,t,n={})=>S(n.key,r=>D(e,t,n,r)),E=(e,t,n,r)=>{let i=r!==b,a=null,c=null;return(l,u)=>{if(u.signal.aborted)return;let d=Date.now(),f=a===null||d-a>=e||d-a<0;return a=d,c!==null&&o(c),c=i?s(r,e):null,n&&f?Promise.resolve(h(u,`debounce`,()=>t(l,u))):(g(u,`debounce`),Promise.resolve(void 0))}},D=(e,n,r,i)=>{let a=r.leading??!1,o=r.trailing??!0;if(!o)return E(e,n,a,i);let s=!1,l=0,u=w(`debounce`,([r,i],a,u)=>{let d=l;return t(a,()=>{l===d&&(s=!1)}),c(a,e).then(()=>{if(s=!1,o&&!i)return u(),n(r,a)})},i);return(e,t)=>{if(t.signal.aborted)return;let r=a&&!s;s=!0,l++;let i=u([e,r],t);return r?Promise.resolve(h(t,`debounce`,()=>n(e,t))):i}},O=(e,n={})=>S(n.key,n=>{let r=null;return(i,a)=>{if(a.signal.aborted)return;if(r){g(a,`leading`);return}let o={};r=o;let s=()=>{c(),r===o&&(r=null,n())},c=t(a,s);try{return u(h(a,`leading`,()=>e(i,a)),s)}catch(e){throw s(),e}}}),k=(e,t={})=>S(t.key,n=>A(e,t,n)),A=(e,n,r)=>{let i=n.concurrency??1,a=n.limit??1/0,o=[],s=0,c=()=>{for(;s<i;){let e=o.shift();if(!e)return;e.start()}};return(l,u)=>new Promise((d,f)=>{if(u.signal.aborted){d(void 0);return}let p=b,m=()=>{p(),g(u,`queue`),d(void 0)},v=()=>{if(p(),u.signal.aborted){m();return}s++;let n=!0,i=()=>{n&&(n=!1,s--,c(),s===0&&o.length===0&&r())},a=t(u,()=>{i(),d(void 0)}),g;try{g=Promise.resolve(h(u,`queue`,()=>e(l,u)))}catch(e){g=Promise.reject(e)}let v=()=>{a(),i()};g.then(e=>{_(u,{value:e}),v(),d(u.signal.aborted?void 0:e)},e=>{_(u,{error:e}),v(),u.signal.aborted?d(void 0):f(e)})};if(s<i){v();return}if(o.length>=a){if(n.overflow!==`drop-old`||a<=0){m();return}o.shift()?.drop()}let y={start:v,drop:m};o.push(y),p=t(u,()=>{let e=o.indexOf(y);e>=0&&o.splice(e,1),m()})})},j=(e,t,n={})=>S(n.key,r=>M(e,t,n,r)),M=(e,t,n,r)=>{let i=n.leading??!0,a=n.trailing??!0,c=r!==b,l=null,u=0,d=null,f=null,p=null,m=!1,_=t=>l===null||t-l>=e||t-l<0||t-u>=e,v=e=>g(e,`throttle`),y=()=>{let e=p;p=null,e&&(v(e.ctx),e.resolve())},x=(e,t)=>(y(),new Promise((n,r)=>{p={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,n,r)=>{y(),u=r,m=!0;try{return h(n,`throttle`,()=>t(e,n))}finally{m=!1}},C=()=>{c&&(f=s(w,e))},w=()=>{if(f=null,!c||d!==null||p)return;let t=Date.now(),n=Math.max(e-(t-(l??-1/0)),e-(t-u));n<=0?r():f=s(w,n)},T=e=>{d=null;let t=p;if(a&&t&&!t.ctx.signal.aborted){p=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else y();w()},E=()=>{let t=Date.now();_(t)?T(t):d=s(E,Math.min(e-(t-(l??t)),e-(t-u)))},D=()=>{f!==null&&(o(f),f=null)},O=(e,t)=>{if(!a)v(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)v(t);else if(u=n,C(),!i)v(t);else return S(e,t,n)},A=(t,n,r,a)=>a&&d!==null?(o(d),d=s(E,e),S(t,n,r)):d===null&&(d=s(E,e),a&&(u=r,i))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!m&&_(n);return l=n,D(),a?A(e,t,n,r):k(e,t,n,r)}},N=Reflect.get(Symbol,`dispose`),P=e=>{let t=new AbortController,n=async(...n)=>{let i=n[0],{ctx:a,unlink:o}=r({event:{type:`withPolicy`,payload:i},parent:{signal:t.signal}});try{return await e(i,a)}finally{o()}},i=e=>{t.abort(e),t=new AbortController},a=Object.assign(n,{cancel:i});return N&&Reflect.set(a,N,()=>i()),a};export{T as debounce,C as latest,O as leading,k as queue,j as throttle,P as withPolicy};
+import{a as e,c as t,i as n,n as r,o as i,t as a}from"./context-yYU3_9lq.js";import{n as o,r as s,t as c}from"./delay-BosJKFjg.js";import{n as l,t as u}from"./promise-CSLpzwSR.js";import{n as d,t as f}from"./lifecycle-key-8iX8RUVD.js";const p=e=>Reflect.get(e,f),m=e=>{p(e)?.start()},h=(t,n,r)=>(m(t),e(t,n,r)),g=(e,t)=>{i(e,t,`drop`),p(e)?.drop()},_=(e,t)=>{p(e)?.done(t)},v=(e,t,n)=>{let r=p(e);t?r?.cancel(n):r?.drop()},y=e=>(Reflect.set(e,d,!0),e),b=()=>{},x=(e,t,n)=>typeof e==`function`?n(e,t??{}):t=>n(t,e??{}),S=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},C=(e,t)=>y(e?S(e,t):t(b));function w(e,t){return x(e,t,T)}const T=(e,t)=>C(t.key,t=>E(`latest`,(t,n,r)=>(r(),e(t,n)),t)),E=(e,r,o=b)=>{let s=null;return(c,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=n(u);s=d;let p=a(d,e),h=!1,g=()=>{d.signal.aborted||(h=!0,m(d),i(d,e,`start`))};t(d,e=>{v(d,h,e),p(h?`cancel`:`drop`)});let _=()=>{f(),s===d&&(s=null,o())},y=e=>{if(!d.signal.aborted)return p(h?`done`:`drop`),e};try{let e=r(c,d,g);return l(e)?Promise.resolve(e).then(y,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(_):(_(),y(e))}catch(e){if(_(),d.signal.aborted)return;throw p(`error`,e),e}}};function D(e,t,n){return x(t,n,(t,n)=>O(e,t,n))}const O=(e,t,n)=>C(n.key,r=>A(e,t,n,r)),k=(e,t,n,r)=>{let i=r!==b,a=null,c=null;return(l,u)=>{if(u.signal.aborted)return;let d=Date.now(),f=a===null||d-a>=e||d-a<0;return a=d,c!==null&&o(c),c=i?s(r,e):null,n&&f?Promise.resolve(h(u,`debounce`,()=>t(l,u))):(g(u,`debounce`),Promise.resolve(void 0))}},A=(e,n,r,i)=>{let a=r.leading??!1,o=r.trailing??!0;if(!o)return k(e,n,a,i);let s=!1,l=0,u=E(`debounce`,([r,i],a,u)=>{let d=l;return t(a,()=>{l===d&&(s=!1)}),c(a,e).then(()=>{if(s=!1,o&&!i)return u(),n(r,a)})},i);return(e,t)=>{if(t.signal.aborted)return;let r=a&&!s;s=!0,l++;let i=u([e,r],t);return r?Promise.resolve(h(t,`debounce`,()=>n(e,t))):i}};function j(e,t){return x(e,t,M)}const M=(e,n)=>C(n.key,n=>{let r=null;return(i,a)=>{if(a.signal.aborted)return;if(r){g(a,`leading`);return}let o={};r=o;let s=()=>{c(),r===o&&(r=null,n())},c=t(a,s);try{return u(h(a,`leading`,()=>e(i,a)),s)}catch(e){throw s(),e}}});function N(e,t){return x(e,t,P)}const P=(e,t)=>C(t.key,n=>F(e,t,n)),F=(e,n,r)=>{let i=n.concurrency??1,a=n.limit??1/0,o=[],s=0,c=()=>{for(;s<i;){let e=o.shift();if(!e)return;e.start()}};return(l,u)=>new Promise((d,f)=>{if(u.signal.aborted){d(void 0);return}let p=b,m=()=>{p(),g(u,`queue`),d(void 0)},v=()=>{if(p(),u.signal.aborted){m();return}s++;let n=!0,i=()=>{n&&(n=!1,s--,c(),s===0&&o.length===0&&r())},a=t(u,()=>{i(),d(void 0)}),g;try{g=Promise.resolve(h(u,`queue`,()=>e(l,u)))}catch(e){g=Promise.reject(e)}let v=()=>{a(),i()};g.then(e=>{_(u,{value:e}),v(),d(u.signal.aborted?void 0:e)},e=>{_(u,{error:e}),v(),u.signal.aborted?d(void 0):f(e)})};if(s<i){v();return}if(o.length>=a){if(n.overflow!==`drop-old`||a<=0){m();return}o.shift()?.drop()}let y={start:v,drop:m};o.push(y),p=t(u,()=>{let e=o.indexOf(y);e>=0&&o.splice(e,1),m()})})};function I(e,t,n){return x(t,n,(t,n)=>L(e,t,n))}const L=(e,t,n)=>C(n.key,r=>R(e,t,n,r)),R=(e,t,n,r)=>{let i=n.leading??!0,a=n.trailing??!0,c=r!==b,l=null,u=0,d=null,f=null,p=null,m=!1,_=t=>l===null||t-l>=e||t-l<0||t-u>=e,v=e=>g(e,`throttle`),y=()=>{let e=p;p=null,e&&(v(e.ctx),e.resolve())},x=(e,t)=>(y(),new Promise((n,r)=>{p={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,n,r)=>{y(),u=r,m=!0;try{return h(n,`throttle`,()=>t(e,n))}finally{m=!1}},C=()=>{c&&(f=s(w,e))},w=()=>{if(f=null,!c||d!==null||p)return;let t=Date.now(),n=Math.max(e-(t-(l??-1/0)),e-(t-u));n<=0?r():f=s(w,n)},T=e=>{d=null;let t=p;if(a&&t&&!t.ctx.signal.aborted){p=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else y();w()},E=()=>{let t=Date.now();_(t)?T(t):d=s(E,Math.min(e-(t-(l??t)),e-(t-u)))},D=()=>{f!==null&&(o(f),f=null)},O=(e,t)=>{if(!a)v(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)v(t);else if(u=n,C(),!i)v(t);else return S(e,t,n)},A=(t,n,r,a)=>a&&d!==null?(o(d),d=s(E,e),S(t,n,r)):d===null&&(d=s(E,e),a&&(u=r,i))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!m&&_(n);return l=n,D(),a?A(e,t,n,r):k(e,t,n,r)}},z=Reflect.get(Symbol,`dispose`),B=e=>{let t=new AbortController,n=async(...n)=>{let i=n[0],{ctx:a,unlink:o}=r({event:{type:`withPolicy`,payload:i},parent:{signal:t.signal}});try{return await e(i,a)}finally{o()}},i=e=>{t.abort(e),t=new AbortController},a=Object.assign(n,{cancel:i});return z&&Reflect.set(a,z,()=>i()),a};export{D as debounce,w as latest,j as leading,N as queue,I as throttle,B as withPolicy};

package/dist/policies.d.ts

@@ -10,6 +10,14 @@ type KeyOption<P> = {
    */
   key?: (payload: P) => unknown;
 };
+/** Options of a policy called without a task: `key` is left out. */
+type Unkeyed<O> = Omit<O, "key"> & {
+  key?: undefined;
+};
+/** Options of a policy called without a task, with a `key` that tells the payload type. */
+type Keyed<O, P> = O & {
+  key: (payload: P) => unknown;
+};
 //#endregion
 //#region src/policies/debounce.d.ts
 type DebounceResult<R> = Promise<R | undefined> | Promise<Awaited<R> | undefined> | undefined;
@@ -19,6 +27,10 @@ type DebounceOptions<P = never> = KeyOption<P> & {
   /** Run the last call of a burst after `ms` of quiet. Default `true`. */
   trailing?: boolean;
 };
+/** What `debounce(ms)` returns: it turns a task into a `debounce` task. */
+type DebounceWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, DebounceResult<R>>;
+/** What `debounce(ms, { key })` returns: the payload type comes from `key`. */
+type KeyedDebounceWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, DebounceResult<R>>;
 /**
  * Waits for `ms` of quiet, then runs; a new call restarts the wait and drops
  * the previous. With `leading` the first call of a burst runs at once, and the
@@ -39,14 +51,24 @@ type DebounceOptions<P = never> = KeyOption<P> & {
  * bus.emit("input", "re"); // only the last call runs, 300 ms after it
  * ```
  */
-export declare const debounce: <P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: DebounceOptions<P>) => Task<P, E, DebounceResult<R>>;
+export declare function debounce<P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: DebounceOptions<P>): Task<P, E, DebounceResult<R>>;
+export declare function debounce(ms: number, options?: Unkeyed<DebounceOptions>): DebounceWrapper;
+export declare function debounce<P>(ms: number, options: Keyed<DebounceOptions<P>, P>): KeyedDebounceWrapper<P>;
 //#endregion
 //#region src/policies/latest.d.ts
 type LatestOptions<P = never> = KeyOption<P>;
+type LatestResult<R> = R | Promise<Awaited<R> | undefined> | undefined;
+/** What `latest()` returns: it turns a task into a `latest` task. */
+type LatestWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, LatestResult<R>>;
+/** What `latest({ key })` returns: the payload type comes from `key`. */
+type KeyedLatestWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, LatestResult<R>>;
 /**
  * Aborts the previous run when a new call arrives; stale results are dropped.
  * With `options.key` each key has its own latest run.
  *
+ * Called without the task, `latest()` returns a function that takes the task,
+ * so `usePolicy(callback, latest())` has no `(task) => ...` to get wrong.
+ *
  * @example
  * ```ts
  * bus.on(
@@ -62,12 +84,21 @@ type LatestOptions<P = never> = KeyOption<P>;
  *
  * // one latest run per user instead of one for all
  * bus.on("load", latest(loadUser, { key: (user) => user.id }));
+ *
+ * // without the task: for a hook that builds the task itself
+ * const search = usePolicy(runSearch, latest());
  * ```
  */
-export declare const latest: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LatestOptions<P>) => Task<P, E, R | Promise<Awaited<R> | undefined> | undefined>;
+export declare function latest<P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LatestOptions<P>): Task<P, E, LatestResult<R>>;
+export declare function latest(options?: Unkeyed<LatestOptions>): LatestWrapper;
+export declare function latest<P>(options: Keyed<LatestOptions<P>, P>): KeyedLatestWrapper<P>;
 //#endregion
 //#region src/policies/leading.d.ts
 type LeadingOptions<P = never> = KeyOption<P>;
+/** What `leading()` returns: it turns a task into a `leading` task. */
+type LeadingWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
+/** What `leading({ key })` returns: the payload type comes from `key`. */
+type KeyedLeadingWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
 /**
  * Drops new calls while the task is still running. The lock is released when
  * the run settles or when its task is aborted, whichever comes first, so a
@@ -87,7 +118,9 @@ type LeadingOptions<P = never> = KeyOption<P>;
  * bus.emit("save", draft); // dropped while the first save is in flight
  * ```
  */
-export declare const leading: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LeadingOptions<P>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
+export declare function leading<P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LeadingOptions<P>): Task<P, E, R | Promise<Awaited<R>> | undefined>;
+export declare function leading(options?: Unkeyed<LeadingOptions>): LeadingWrapper;
+export declare function leading<P>(options: Keyed<LeadingOptions<P>, P>): KeyedLeadingWrapper<P>;
 //#endregion
 //#region src/policies/queue.d.ts
 type QueueOptions<P = never> = KeyOption<P> & {
@@ -102,6 +135,10 @@ type QueueOptions<P = never> = KeyOption<P> & {
    */
   overflow?: "drop-new" | "drop-old";
 };
+/** What `queue()` returns: it turns a task into a `queue` task. */
+type QueueWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, Promise<Awaited<R> | undefined>>;
+/** What `queue({ key })` returns: the payload type comes from `key`. */
+type KeyedQueueWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, Promise<Awaited<R> | undefined>>;
 /**
  * Runs calls one after another, in the order they arrived: a call starts when
  * fewer than `concurrency` calls are running. Every call returns a promise with
@@ -132,7 +169,9 @@ type QueueOptions<P = never> = KeyOption<P> & {
  * bus.emit("save", b); // waits for a, then runs
  * ```
  */
-export declare const queue: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: QueueOptions<P>) => Task<P, E, Promise<Awaited<R> | undefined>>;
+export declare function queue<P, E extends EventMap, R>(fn: Task<P, E, R>, options?: QueueOptions<P>): Task<P, E, Promise<Awaited<R> | undefined>>;
+export declare function queue(options?: Unkeyed<QueueOptions>): QueueWrapper;
+export declare function queue<P>(options: Keyed<QueueOptions<P>, P>): KeyedQueueWrapper<P>;
 //#endregion
 //#region src/policies/throttle.d.ts
 type ThrottleOptions<P = never> = KeyOption<P> & {
@@ -141,6 +180,10 @@ type ThrottleOptions<P = never> = KeyOption<P> & {
   /** Run the latest call made while waiting, at the end of the window. Default `true`. */
   trailing?: boolean;
 };
+/** What `throttle(ms)` returns: it turns a task into a `throttle` task. */
+type ThrottleWrapper = <P, E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<R | undefined> | undefined>;
+/** What `throttle(ms, { key })` returns: the payload type comes from `key`. */
+type KeyedThrottleWrapper<P> = <E extends EventMap, R>(fn: Task<P, E, R>) => Task<P, E, R | Promise<R | undefined> | undefined>;
 /**
  * At most one run per `ms`, with the semantics of lodash `throttle` (and
  * patronum): a call made when the throttle is idle, that is, at least `ms`
@@ -167,6 +210,8 @@ type ThrottleOptions<P = never> = KeyOption<P> & {
  * bus.emit("scroll", 30); // runs once the 200 ms window closes
  * ```
  */
-export declare const throttle: <P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: ThrottleOptions<P>) => Task<P, E, R | Promise<R | undefined> | undefined>;
+export declare function throttle<P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: ThrottleOptions<P>): Task<P, E, R | Promise<R | undefined> | undefined>;
+export declare function throttle(ms: number, options?: Unkeyed<ThrottleOptions>): ThrottleWrapper;
+export declare function throttle<P>(ms: number, options: Keyed<ThrottleOptions<P>, P>): KeyedThrottleWrapper<P>;
 //#endregion
 export { type DebounceOptions, type LatestOptions, type LeadingOptions, type PolicyFunction, type QueueOptions, type ThrottleOptions, withPolicy };

package/dist/policies.js

@@ -1 +1 @@
-import{i as e,o as t,s as n,t as r,u as i}from"./context-CJGW6OWj.js";import{n as a,r as o,t as s}from"./delay-BnBdGPh7.js";import{n as c,t as l}from"./promise-CSLpzwSR.js";import{n as u,t as d}from"./lifecycle-key-8iX8RUVD.js";import{t as f}from"./with-policy-CW50Edgk.js";const p=e=>Reflect.get(e,d),m=e=>{p(e)?.start()},h=(e,n,r)=>(m(e),t(e,n,r)),g=(e,t)=>{n(e,t,`drop`),p(e)?.drop()},_=(e,t)=>{p(e)?.done(t)},v=(e,t,n)=>{let r=p(e);t?r?.cancel(n):r?.drop()},y=e=>(Reflect.set(e,u,!0),e),b=()=>{},x=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},S=(e,t)=>y(e?x(e,t):t(b)),C=(e,t={})=>S(t.key,t=>w(`latest`,(t,n,r)=>(r(),e(t,n)),t)),w=(t,a,o=b)=>{let s=null;return(l,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=e(u);s=d;let p=r(d,t),h=!1,g=()=>{d.signal.aborted||(h=!0,m(d),n(d,t,`start`))};i(d,e=>{v(d,h,e),p(h?`cancel`:`drop`)});let _=()=>{f(),s===d&&(s=null,o())},y=e=>{if(!d.signal.aborted)return p(h?`done`:`drop`),e};try{let e=a(l,d,g);return c(e)?Promise.resolve(e).then(y,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(_):(_(),y(e))}catch(e){if(_(),d.signal.aborted)return;throw p(`error`,e),e}}},T=(e,t,n={})=>S(n.key,r=>D(e,t,n,r)),E=(e,t,n,r)=>{let i=r!==b,s=null,c=null;return(l,u)=>{if(u.signal.aborted)return;let d=Date.now(),f=s===null||d-s>=e||d-s<0;return s=d,c!==null&&a(c),c=i?o(r,e):null,n&&f?Promise.resolve(h(u,`debounce`,()=>t(l,u))):(g(u,`debounce`),Promise.resolve(void 0))}},D=(e,t,n,r)=>{let a=n.leading??!1,o=n.trailing??!0;if(!o)return E(e,t,a,r);let c=!1,l=0,u=w(`debounce`,([n,r],a,u)=>{let d=l;return i(a,()=>{l===d&&(c=!1)}),s(a,e).then(()=>{if(c=!1,o&&!r)return u(),t(n,a)})},r);return(e,n)=>{if(n.signal.aborted)return;let r=a&&!c;c=!0,l++;let i=u([e,r],n);return r?Promise.resolve(h(n,`debounce`,()=>t(e,n))):i}},O=(e,t={})=>S(t.key,t=>{let n=null;return(r,a)=>{if(a.signal.aborted)return;if(n){g(a,`leading`);return}let o={};n=o;let s=()=>{c(),n===o&&(n=null,t())},c=i(a,s);try{return l(h(a,`leading`,()=>e(r,a)),s)}catch(e){throw s(),e}}}),k=(e,t={})=>S(t.key,n=>A(e,t,n)),A=(e,t,n)=>{let r=t.concurrency??1,a=t.limit??1/0,o=[],s=0,c=()=>{for(;s<r;){let e=o.shift();if(!e)return;e.start()}};return(l,u)=>new Promise((d,f)=>{if(u.signal.aborted){d(void 0);return}let p=b,m=()=>{p(),g(u,`queue`),d(void 0)},v=()=>{if(p(),u.signal.aborted){m();return}s++;let t=!0,r=()=>{t&&(t=!1,s--,c(),s===0&&o.length===0&&n())},a=i(u,()=>{r(),d(void 0)}),g;try{g=Promise.resolve(h(u,`queue`,()=>e(l,u)))}catch(e){g=Promise.reject(e)}let v=()=>{a(),r()};g.then(e=>{_(u,{value:e}),v(),d(u.signal.aborted?void 0:e)},e=>{_(u,{error:e}),v(),u.signal.aborted?d(void 0):f(e)})};if(s<r){v();return}if(o.length>=a){if(t.overflow!==`drop-old`||a<=0){m();return}o.shift()?.drop()}let y={start:v,drop:m};o.push(y),p=i(u,()=>{let e=o.indexOf(y);e>=0&&o.splice(e,1),m()})})},j=(e,t,n={})=>S(n.key,r=>M(e,t,n,r)),M=(e,t,n,r)=>{let i=n.leading??!0,s=n.trailing??!0,c=r!==b,l=null,u=0,d=null,f=null,p=null,m=!1,_=t=>l===null||t-l>=e||t-l<0||t-u>=e,v=e=>g(e,`throttle`),y=()=>{let e=p;p=null,e&&(v(e.ctx),e.resolve())},x=(e,t)=>(y(),new Promise((n,r)=>{p={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,n,r)=>{y(),u=r,m=!0;try{return h(n,`throttle`,()=>t(e,n))}finally{m=!1}},C=()=>{c&&(f=o(w,e))},w=()=>{if(f=null,!c||d!==null||p)return;let t=Date.now(),n=Math.max(e-(t-(l??-1/0)),e-(t-u));n<=0?r():f=o(w,n)},T=e=>{d=null;let t=p;if(s&&t&&!t.ctx.signal.aborted){p=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else y();w()},E=()=>{let t=Date.now();_(t)?T(t):d=o(E,Math.min(e-(t-(l??t)),e-(t-u)))},D=()=>{f!==null&&(a(f),f=null)},O=(e,t)=>{if(!s)v(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)v(t);else if(u=n,C(),!i)v(t);else return S(e,t,n)},A=(t,n,r,s)=>s&&d!==null?(a(d),d=o(E,e),S(t,n,r)):d===null&&(d=o(E,e),s&&(u=r,i))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!m&&_(n);return l=n,D(),s?A(e,t,n,r):k(e,t,n,r)}};export{T as debounce,C as latest,O as leading,k as queue,j as throttle,f as withPolicy};
+import{i as e,o as t,s as n,t as r,u as i}from"./context-CJGW6OWj.js";import{n as a,r as o,t as s}from"./delay-BnBdGPh7.js";import{n as c,t as l}from"./promise-CSLpzwSR.js";import{n as u,t as d}from"./lifecycle-key-8iX8RUVD.js";import{t as f}from"./with-policy-CW50Edgk.js";const p=e=>Reflect.get(e,d),m=e=>{p(e)?.start()},h=(e,n,r)=>(m(e),t(e,n,r)),g=(e,t)=>{n(e,t,`drop`),p(e)?.drop()},_=(e,t)=>{p(e)?.done(t)},v=(e,t,n)=>{let r=p(e);t?r?.cancel(n):r?.drop()},y=e=>(Reflect.set(e,u,!0),e),b=()=>{},x=(e,t,n)=>typeof e==`function`?n(e,t??{}):t=>n(t,e??{}),S=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},C=(e,t)=>y(e?S(e,t):t(b));function w(e,t){return x(e,t,T)}const T=(e,t)=>C(t.key,t=>E(`latest`,(t,n,r)=>(r(),e(t,n)),t)),E=(t,a,o=b)=>{let s=null;return(l,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=e(u);s=d;let p=r(d,t),h=!1,g=()=>{d.signal.aborted||(h=!0,m(d),n(d,t,`start`))};i(d,e=>{v(d,h,e),p(h?`cancel`:`drop`)});let _=()=>{f(),s===d&&(s=null,o())},y=e=>{if(!d.signal.aborted)return p(h?`done`:`drop`),e};try{let e=a(l,d,g);return c(e)?Promise.resolve(e).then(y,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(_):(_(),y(e))}catch(e){if(_(),d.signal.aborted)return;throw p(`error`,e),e}}};function D(e,t,n){return x(t,n,(t,n)=>O(e,t,n))}const O=(e,t,n)=>C(n.key,r=>A(e,t,n,r)),k=(e,t,n,r)=>{let i=r!==b,s=null,c=null;return(l,u)=>{if(u.signal.aborted)return;let d=Date.now(),f=s===null||d-s>=e||d-s<0;return s=d,c!==null&&a(c),c=i?o(r,e):null,n&&f?Promise.resolve(h(u,`debounce`,()=>t(l,u))):(g(u,`debounce`),Promise.resolve(void 0))}},A=(e,t,n,r)=>{let a=n.leading??!1,o=n.trailing??!0;if(!o)return k(e,t,a,r);let c=!1,l=0,u=E(`debounce`,([n,r],a,u)=>{let d=l;return i(a,()=>{l===d&&(c=!1)}),s(a,e).then(()=>{if(c=!1,o&&!r)return u(),t(n,a)})},r);return(e,n)=>{if(n.signal.aborted)return;let r=a&&!c;c=!0,l++;let i=u([e,r],n);return r?Promise.resolve(h(n,`debounce`,()=>t(e,n))):i}};function j(e,t){return x(e,t,M)}const M=(e,t)=>C(t.key,t=>{let n=null;return(r,a)=>{if(a.signal.aborted)return;if(n){g(a,`leading`);return}let o={};n=o;let s=()=>{c(),n===o&&(n=null,t())},c=i(a,s);try{return l(h(a,`leading`,()=>e(r,a)),s)}catch(e){throw s(),e}}});function N(e,t){return x(e,t,P)}const P=(e,t)=>C(t.key,n=>F(e,t,n)),F=(e,t,n)=>{let r=t.concurrency??1,a=t.limit??1/0,o=[],s=0,c=()=>{for(;s<r;){let e=o.shift();if(!e)return;e.start()}};return(l,u)=>new Promise((d,f)=>{if(u.signal.aborted){d(void 0);return}let p=b,m=()=>{p(),g(u,`queue`),d(void 0)},v=()=>{if(p(),u.signal.aborted){m();return}s++;let t=!0,r=()=>{t&&(t=!1,s--,c(),s===0&&o.length===0&&n())},a=i(u,()=>{r(),d(void 0)}),g;try{g=Promise.resolve(h(u,`queue`,()=>e(l,u)))}catch(e){g=Promise.reject(e)}let v=()=>{a(),r()};g.then(e=>{_(u,{value:e}),v(),d(u.signal.aborted?void 0:e)},e=>{_(u,{error:e}),v(),u.signal.aborted?d(void 0):f(e)})};if(s<r){v();return}if(o.length>=a){if(t.overflow!==`drop-old`||a<=0){m();return}o.shift()?.drop()}let y={start:v,drop:m};o.push(y),p=i(u,()=>{let e=o.indexOf(y);e>=0&&o.splice(e,1),m()})})};function I(e,t,n){return x(t,n,(t,n)=>L(e,t,n))}const L=(e,t,n)=>C(n.key,r=>R(e,t,n,r)),R=(e,t,n,r)=>{let i=n.leading??!0,s=n.trailing??!0,c=r!==b,l=null,u=0,d=null,f=null,p=null,m=!1,_=t=>l===null||t-l>=e||t-l<0||t-u>=e,v=e=>g(e,`throttle`),y=()=>{let e=p;p=null,e&&(v(e.ctx),e.resolve())},x=(e,t)=>(y(),new Promise((n,r)=>{p={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,n,r)=>{y(),u=r,m=!0;try{return h(n,`throttle`,()=>t(e,n))}finally{m=!1}},C=()=>{c&&(f=o(w,e))},w=()=>{if(f=null,!c||d!==null||p)return;let t=Date.now(),n=Math.max(e-(t-(l??-1/0)),e-(t-u));n<=0?r():f=o(w,n)},T=e=>{d=null;let t=p;if(s&&t&&!t.ctx.signal.aborted){p=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else y();w()},E=()=>{let t=Date.now();_(t)?T(t):d=o(E,Math.min(e-(t-(l??t)),e-(t-u)))},D=()=>{f!==null&&(a(f),f=null)},O=(e,t)=>{if(!s)v(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)v(t);else if(u=n,C(),!i)v(t);else return S(e,t,n)},A=(t,n,r,s)=>s&&d!==null?(a(d),d=o(E,e),S(t,n,r)):d===null&&(d=o(E,e),s&&(u=r,i))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!m&&_(n);return l=n,D(),s?A(e,t,n,r):k(e,t,n,r)}};export{D as debounce,w as latest,j as leading,N as queue,I as throttle,f as withPolicy};

package/dist/react.d.ts

@@ -85,9 +85,11 @@ export declare const reactPlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus
  * render. This hook keeps the policy across renders and calls the `callback` of
  * the latest render, so an inline callback sees fresh props and state.
  *
- * `make` gets a task that runs the callback and returns the policy built around
- * it. It runs once, and again when an item of `deps` changes: list there what
- * `make` reads, such as the wait time. The pending calls of the old function are
+ * `make` builds the policy around the callback. Pass a policy called without
+ * its task (`debounce(300)`, `latest()`), or a function `(task) => policy` for
+ * a combined policy such as `(task) => throttle(100, latest(task))`; `task`
+ * runs the callback. `make` runs once, and again when an item of `deps`
+ * changes: list there what it reads, such as the wait time. The pending calls of the old function are
  * cancelled then, and when the component unmounts. Needs `react` 18 or newer.
  *
  * @example
@@ -99,7 +101,7 @@ export declare const reactPlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus
  *   const [results, setResults] = useState([]);
  *   const onChange = usePolicy(
  *     async (query: string) => setResults(await search(query)), // latest render's callback
- *     (task) => debounce(wait, task), // the policy, made once per wait
+ *     debounce(wait), // the policy, made once per wait
  *     [wait],
  *   );
  *   return <input onChange={(event) => onChange(event.target.value)} />;

package/docs/chat-example.md

@@ -44,7 +44,7 @@ Each domain is a folder. The components only emit events and read values; they n
 | `src/domains/incoming/` | New messages, asked for at an interval. |
 | `src/ui/` | The components. |
 
-A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store.
+A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any domain may listen: `rooms/selected` is heard by three. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 ## Load a history that must not race
 
@@ -173,19 +173,24 @@ export const runSearch = debounce(
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
 ```js
+import { createCommand } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
+// createCommand — an order for the messages domain, with the handler that does it
+const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
+
 // the room that is open, kept from the rooms/selected event
 let selectedRoom = "general";
 
-export const openResult = async (hit, ctx) => {
+export const goToResult = async (hit, ctx) => {
   if (hit.roomId !== selectedRoom) {
     // take — wait for the next event of that name; started before the emit so nothing is missed
     const loaded = take(ctx, "messages/loadHistory/success");
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  ctx.emit("messages/marked", hit.id);
+  // ctx.emit with a command — the messages domain marks the message
+  ctx.emit(markMessage(hit.id));
 };
 ```
 

package/docs/policies.md

@@ -36,6 +36,33 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
+## Call a policy without its function
+
+**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+
+**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them as before: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+
 ## Configure debounce and throttle
 
 `debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.

package/docs/query-libraries.md

@@ -122,3 +122,5 @@ Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the c
 - **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Commands that fetch are async, so this only matters for a sync handler that sets up a callback.
 - **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
 - **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
+
+A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).

package/docs/react.md

@@ -248,8 +248,8 @@ export const Search = ({ wait }) => {
       const found = await api.search(query, { signal });
       setItems(found);
     },
-    // the second argument builds the policy once; task runs the callback above
-    (task) => debounce(wait, task),
+    // debounce(wait) — the second argument builds the policy once around the callback above
+    debounce(wait),
     // deps — list what the second argument reads; a new wait makes a new policy
     [wait],
   );
@@ -265,7 +265,9 @@ export const Search = ({ wait }) => {
 
 - `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
 - A pending call is cancelled on unmount and when `deps` change.
-- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
+- To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
+- `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
 - Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
 
 ## Where to go next

package/docs/starter.md

@@ -48,6 +48,7 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
 | `domains-ts` | Commands, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
 | `vue-ts` | The `react-ts` app in Vue 3, with `watchEmitter` and `useEventRef` from `nanoeffects/vue` | You build a Vue 3 app |
+| `svelte-ts` | The `react-ts` app in Svelte 5, with a Svelte store made from an event | You build a Svelte app |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -71,6 +72,16 @@ npm create nanoeffects@latest my-app -- --template vue-ts
 
 `npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
 
+### Start with Svelte
+
+`svelte-ts` is the search app of `react-ts` in Svelte 5. It needs no part of nanoeffects for Svelte: a Svelte store is any object with `subscribe`, so a small helper of the project, `src/event-store.ts`, makes a store from an event with `readable` and `bus.on`. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](react.md#show-the-last-value-of-an-event-as-state): a value that several components share belongs in a store of your own.
+
+```bash
+npm create nanoeffects@latest my-app -- --template svelte-ts
+```
+
+`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+
 ### Start with domains
 
 `domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
@@ -93,7 +104,7 @@ The commands, jobs and modules themselves are explained in [Actions, commands, j
 
 ## Read the files
 
-Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components).
+Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
 
 | File | Job |
 | ---- | --- |

package/llms-full.txt

@@ -553,6 +553,7 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
 | `domains-ts` | Commands, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
 | `vue-ts` | The `react-ts` app in Vue 3, with `watchEmitter` and `useEventRef` from `nanoeffects/vue` | You build a Vue 3 app |
+| `svelte-ts` | The `react-ts` app in Svelte 5, with a Svelte store made from an event | You build a Svelte app |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -576,6 +577,16 @@ npm create nanoeffects@latest my-app -- --template vue-ts
 
 `npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
 
+### Start with Svelte
+
+`svelte-ts` is the search app of `react-ts` in Svelte 5. It needs no part of nanoeffects for Svelte: a Svelte store is any object with `subscribe`, so a small helper of the project, `src/event-store.ts`, makes a store from an event with `readable` and `bus.on`. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](react.md#show-the-last-value-of-an-event-as-state): a value that several components share belongs in a store of your own.
+
+```bash
+npm create nanoeffects@latest my-app -- --template svelte-ts
+```
+
+`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+
 ### Start with domains
 
 `domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
@@ -598,7 +609,7 @@ The commands, jobs and modules themselves are explained in [Actions, commands, j
 
 ## Read the files
 
-Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components).
+Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
 
 | File | Job |
 | ---- | --- |
@@ -1069,6 +1080,33 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
+## Call a policy without its function
+
+**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+
+**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them as before: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+
 ## Configure debounce and throttle
 
 `debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.
@@ -3022,6 +3060,8 @@ Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the c
 - **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
 - **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
 
+A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).
+
 ---
 Source: docs/react.md
 
@@ -3275,8 +3315,8 @@ export const Search = ({ wait }) => {
       const found = await api.search(query, { signal });
       setItems(found);
     },
-    // the second argument builds the policy once; task runs the callback above
-    (task) => debounce(wait, task),
+    // debounce(wait) — the second argument builds the policy once around the callback above
+    debounce(wait),
     // deps — list what the second argument reads; a new wait makes a new policy
     [wait],
   );
@@ -3292,7 +3332,9 @@ export const Search = ({ wait }) => {
 
 - `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
 - A pending call is cancelled on unmount and when `deps` change.
-- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
+- To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
+- `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
 - Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
 
 ## Where to go next
@@ -3352,7 +3394,7 @@ Each domain is a folder. The components only emit events and read values; they n
 | `src/domains/incoming/` | New messages, asked for at an interval. |
 | `src/ui/` | The components. |
 
-A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store.
+A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any domain may listen: `rooms/selected` is heard by three. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 ## Load a history that must not race
 
@@ -3481,19 +3523,24 @@ export const runSearch = debounce(
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
 ```js
+import { createCommand } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
+// createCommand — an order for the messages domain, with the handler that does it
+const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
+
 // the room that is open, kept from the rooms/selected event
 let selectedRoom = "general";
 
-export const openResult = async (hit, ctx) => {
+export const goToResult = async (hit, ctx) => {
   if (hit.roomId !== selectedRoom) {
     // take — wait for the next event of that name; started before the emit so nothing is missed
     const loaded = take(ctx, "messages/loadHistory/success");
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  ctx.emit("messages/marked", hit.id);
+  // ctx.emit with a command — the messages domain marks the message
+  ctx.emit(markMessage(hit.id));
 };
 ```
 

package/llms.txt

@@ -15,7 +15,7 @@ Rules that generated code often gets wrong:
 ## Start here
 
 - [Guide](docs/guide.md): bus, handler context, policies, effects, commands and modules, step by step
-- [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla`, `react`, `vue-ts` and others, in JavaScript or TypeScript) with a bus, `debounce` and `latest`
+- [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla`, `react`, `vue-ts`, `svelte-ts` and others, in JavaScript or TypeScript) with a bus, `debounce` and `latest`
 - [Why nanoeffects exists](docs/motivation.md): no dependencies and no global state for SDKs and Module Federation, and why not Redux, Effector or RxJS
 - [Package entries](docs/package.md): which import holds what
 - [Plugins](docs/plugins.md): every plugin of a bus, what `bus.use` returns, and the order to use them in

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.20.0",
+	"version": "0.21.0",
 	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -166,6 +166,7 @@
 		"@reduxjs/toolkit": "^2.13.0",
 		"@size-limit/esbuild": "^14.2.0",
 		"@size-limit/file": "^14.2.0",
+		"@tanstack/react-query": "^5.105.0",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
 		"@vitejs/plugin-react": "^6.1.2",
@@ -206,7 +207,7 @@
 		{
 			"name": "policies (all)",
 			"path": "dist/policies.js",
-			"limit": "2.6 kB"
+			"limit": "2.65 kB"
 		},
 		{
 			"name": "effects (all)",