@picked/svelte 0.0.23 → 0.0.24-next.1

package/dist/hooks/create-query/index.d.ts

@@ -0,0 +1,145 @@
+import { Store } from 'effector';
+interface QueryOptions {
+    refetch?: boolean;
+    staleTime?: number;
+    retry?: number;
+    retryDelay?: number;
+}
+export interface QueryResult<T> {
+    data: Store<T | null>;
+    error: Store<Error | null>;
+    isLoading: Store<boolean>;
+    refetch: () => Promise<T>;
+    invalidate: () => void;
+}
+export type QueryFactory<Params, Results> = (params: Params, queryOptions?: QueryOptions) => QueryResult<Results>;
+/**
+ * Effector-powered data fetching helper inspired by [SWR](https://www.npmjs.com/package/swr).
+ *
+ * It provides:
+ * - Request de-duplication per key (in-flight promise reuse)
+ * - Stale-while-revalidate caching with per-key timestamps
+ * - Automatic retries with exponential backoff
+ * - Fine-grained invalidation (per key, per namespace, or global)
+ *
+ * Behavior overview:
+ * - Cache key: built from the `keyFn(params)` within a `namespace` to avoid collisions across domains.
+ * - Staleness: when a record is older than `staleTime`, the next read will revalidate in the background.
+ * - Deduplication: concurrent reads for the same key share the same promise.
+ * - Retries: failures are retried up to `retry` times using exponential backoff starting at `retryDelay` ms.
+ *
+ * Type parameters:
+ * - Params: the shape of parameters passed to the fetcher
+ * - Results: the shape of the resolved fetcher result
+ *
+ * @param fetcher A function that performs the async request and returns a Promise of the result.
+ * @param keyFn A function that builds a stable cache key from the provided params.
+ *               Use all inputs that affect the result to prevent collisions.
+ * @param options Optional configuration applied to all queries created by this factory.
+ * @param options.namespace Logical grouping for cache separation. Defaults to "default".
+ * @param options.defaultStaleTime Default time in ms before data is considered stale. Defaults to 5 minutes.
+ * @param options.defaultRetry Default max retry attempts on failure. Defaults to 3.
+ * @param options.defaultRetryDelay Base delay in ms for retries; exponential backoff is applied. Defaults to 1000ms.
+ *
+ * @returns A QueryFactory(params, queryOptions) that produces QueryResult stores and controls for a specific key.
+ *
+ * Example: Basic usage with request de-duplication and caching
+ * ```typescript
+ * type User = { id: string; name: string }
+ *
+ * async function fetchUser({ id }: { id: string }): Promise<User> {
+ *   const res = await fetch(`/api/users/${id}`)
+ *   if (!res.ok) throw new Error('Failed to load user')
+ *   return res.json()
+ * }
+ *
+ * const userQuery = createQuery(fetchUser, (p) => `user:${p.id}`, {
+ *   namespace: 'users',
+ *   defaultStaleTime: 60_000, // 1 minute
+ *   defaultRetry: 2,
+ *   defaultRetryDelay: 500,
+ * })
+ *
+ * // Later in your code (each call uses the same key -> dedup + cache)
+ * const { data, error, isLoading, refetch, invalidate } = userQuery({ id: '42' })
+ *
+ * // Subscribe reactively via Effector API:
+ * const stopDataWatch = data.watch((value) => {
+ *   console.log('User data changed:', value)
+ * })
+ * const stopErrorWatch = error.watch((err) => {
+ *   if (err) console.error('User query error:', err)
+ * })
+ * const stopLoadingWatch = isLoading.watch((pending) => {
+ *   console.log('Loading:', pending)
+ * })
+ *
+ * // Manually refetch (ignores staleness)
+ * refetch()
+ *
+ * // Invalidate only this key (forces next read to refetch)
+ * invalidate()
+ *
+ * // Clean up watchers when leaving scope
+ * stopDataWatch()
+ * stopErrorWatch()
+ * stopLoadingWatch()
+ * ```
+ *
+ * Example: Per-call overrides (staleTime, retry)
+ * ```typescript
+ * const fastUserQuery = createQuery(fetchUser, (p) => `user:${p.id}`, {
+ *   namespace: 'users',
+ *   defaultStaleTime: 5 * 60_000, // 5 minutes
+ * })
+ *
+ * // For this call, we want fresher data and fewer retries:
+ * const fast = fastUserQuery({ id: '42' }, { staleTime: 5_000, retry: 1 })
+ *
+ * // For another call, rely on defaults:
+ * const normal = fastUserQuery({ id: '42' })
+ * ```
+ *
+ * Example: Using multiple params in the key
+ * ```typescript
+ * type ListParams = { page: number; q?: string }
+ * const listQuery = createQuery(
+ *   async (p: ListParams) => {
+ *     const u = new URL('/api/items', window.location.origin)
+ *     u.searchParams.set('page', String(p.page))
+ *     if (p.q) u.searchParams.set('q', p.q)
+ *     const r = await fetch(u)
+ *     if (!r.ok) throw new Error('Failed')
+ *     return r.json() as Promise<{ items: unknown[]; total: number }>
+ *   },
+ *   // Include all inputs that affect response:
+ *   (p) => `items:page=${p.page}:q=${p.q ?? ''}`,
+ *   { namespace: 'items' },
+ * )
+ * ```
+ */
+export declare function createQuery<Params, Results>(fetcher: (params: Params) => Promise<Results>, keyFn: (params: Params) => string, options?: {
+    namespace?: string;
+    defaultStaleTime?: number;
+    defaultRetry?: number;
+    defaultRetryDelay?: number;
+}): QueryFactory<Params, Results>;
+export declare const queryCache: {
+    invalidate: (namespace: string, key?: string) => void;
+    clear: () => void;
+};
+export declare const queryPresets: {
+    realtime: {
+        defaultStaleTime: number;
+        defaultRetry: number;
+    };
+    standard: {
+        defaultStaleTime: number;
+        defaultRetry: number;
+    };
+    static: {
+        defaultStaleTime: number;
+        defaultRetry: number;
+    };
+};
+export {};

package/dist/hooks/create-query/index.js

@@ -0,0 +1 @@
+import{createEffect as E,createStore as w,sample as S}from"effector";const y=new Map;function T(a){return y.has(a)||y.set(a,new Map),y.get(a)}function R(a,i){const o=T(a).get(i);o&&(o.promise=null,o.timestamp=0)}function v(a){T(a).forEach(c=>{c.promise=null,c.timestamp=0})}function L(){y.clear()}function P(a,i,c={}){const{namespace:o="default",defaultStaleTime:f=300*1e3,defaultRetry:m=3,defaultRetryDelay:g=1e3}=c,u=T(o),d=E(async p=>{var D;const{key:s,params:l,options:e}=p;let r=(D=u.get(s))==null?void 0:D.promise;const t=u.get(s),n=e.refetch||!r||t&&Date.now()-t.timestamp>(e.staleTime??t.staleTime);if(!r||n){r=_(()=>a(l),e.retry??m,e.retryDelay??g);const h=u.get(s);h&&(h.promise=r,h.timestamp=Date.now(),h.staleTime=e.staleTime??f)}return{key:s,promise:r,result:await r}});return(p,s={})=>{const l=i(p);let e=u.get(l);e||(e={promise:null,data:w(null),error:w(null),isLoading:w(!1),timestamp:0,staleTime:s.staleTime??f},u.set(l,e));const r=E(t=>t);return S({source:d.doneData,filter:t=>t.key===l,fn:t=>t.promise,target:r}),e.isLoading.on(d.pending,(t,n)=>n),e.isLoading.on(r.pending,(t,n)=>n),e.data.on(r.doneData,(t,n)=>n),e.error.on(r.doneData,()=>null),e.error.on(r.failData,(t,n)=>n),e.error.on(d.failData,(t,n)=>n),(!e.promise||Date.now()-e.timestamp>e.staleTime)&&d({key:l,params:p,options:s}),{data:e.data,error:e.error,isLoading:e.isLoading,refetch:()=>d({key:l,params:p,options:{...s,refetch:!0}}).then(({result:t})=>t),invalidate:()=>R(o,l)}}}async function _(a,i,c){let o;for(let f=0;f<=i;f++)try{return await a()}catch(m){o=m instanceof Error?m:new Error(String(m)),f<i&&await new Promise(g=>{setTimeout(g,c*Math.pow(2,f))})}throw o}const M={invalidate:(a,i)=>{i?R(a,i):v(a)},clear:()=>L()},b={realtime:{defaultStaleTime:5*1e3,defaultRetry:1},standard:{defaultStaleTime:300*1e3,defaultRetry:3},static:{defaultStaleTime:3600*1e3,defaultRetry:2}};export{P as createQuery,M as queryCache,b as queryPresets};

package/dist/hooks/index.d.ts

@@ -3,3 +3,4 @@ export { getStep, setStepContext } from './step';
 export { useUnit, getContextScope, setContextScope } from './stores';
 export { createSessionStorageStore, createLocalStorageStore } from './storage.js';
 export { getTrackRecommendationPresentEvent } from './events';
+export { createQuery, queryCache, queryPresets, type QueryResult, type QueryFactory, } from './create-query';

package/dist/hooks/index.js

@@ -1 +1 @@
-import{getExperience as o,getPicked as r}from"./client.js";import{getStep as p,setStepContext as c}from"./step.js";import{getContextScope as S,setContextScope as a,useUnit as g}from"./stores.js";import{createLocalStorageStore as s,createSessionStorageStore as f}from"./storage.js";import{getTrackRecommendationPresentEvent as C}from"./events.js";export{s as createLocalStorageStore,f as createSessionStorageStore,S as getContextScope,o as getExperience,r as getPicked,p as getStep,C as getTrackRecommendationPresentEvent,a as setContextScope,c as setStepContext,g as useUnit};
+import{getExperience as r,getPicked as o}from"./client.js";import{getStep as p,setStepContext as n}from"./step.js";import{getContextScope as a,setContextScope as S,useUnit as m}from"./stores.js";import{createLocalStorageStore as g,createSessionStorageStore as f}from"./storage.js";import{getTrackRecommendationPresentEvent as u}from"./events.js";import{createQuery as y,queryCache as P,queryPresets as d}from"./create-query/index.js";export{g as createLocalStorageStore,y as createQuery,f as createSessionStorageStore,a as getContextScope,r as getExperience,o as getPicked,p as getStep,u as getTrackRecommendationPresentEvent,P as queryCache,d as queryPresets,S as setContextScope,n as setStepContext,m as useUnit};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picked/svelte",
-  "version": "0.0.23",
+  "version": "0.0.24-next.1",
   "dependencies": {
     "d3": "^7.9.0"
   },
@@ -14,13 +14,17 @@
     "@tsconfig/svelte": "^5.0.4",
     "@types/d3": "^7.4.3",
     "@types/node": "^22",
+    "@vitest/coverage-v8": "^3.2.4",
     "effector": "^23.3.0",
     "fast-glob": "^3.3.3",
+    "happy-dom": "^20.0.2",
+    "svelte": "^5.34.3",
     "svelte-check": "^4.2.2",
     "typedoc": "^0.28.5",
     "typedoc-plugin-markdown": "^4.6.3",
     "vite": "^6.4.1",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
   },
   "exports": {
     ".": {
@@ -71,7 +75,7 @@
   ],
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@picked/client": "0.0.23",
+    "@picked/client": "0.0.24-next.1",
     "effector": "^23.3.0",
     "svelte": "^5.34.3"
   },
@@ -85,7 +89,10 @@
     "lint:format": "eslint . --fix",
     "lint:report": "eslint . -o './.reports/eslint.json' -f json || [ -f './.reports/eslint.json' ]",
     "svelte-check:report": "mkdir -p ./.reports && pnpm svelte-check --tsconfig ./tsconfig.json --output=machine > ./.reports/svelte-check.txt || [ -f './.reports/svelte-check.txt' ]",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:packaged-types": "attw --pack",
+    "test:watch": "vitest",
     "type-check": "tsc -p . --noEmit"
   },
   "svelte": "./dist/index.js",