@studiolambda/query 1.0.0 → 1.1.1

package/dist/src/query/options.d.ts

@@ -0,0 +1,263 @@
+import { Cache, Caches, CacheType, ItemsCacheItem, ResolversCacheItem } from './cache';
+/**
+ * Represents the available configuration options
+ * for a query instance.
+ */
+export interface Configuration extends Options {
+    /**
+     * Determines the resolved items cache to use.
+     */
+    readonly itemsCache?: Cache<ItemsCacheItem>;
+    /**
+     * Determines the resolvers cache to use.
+     */
+    readonly resolversCache?: Cache<ResolversCacheItem>;
+    /**
+     * Stores the event system.
+     */
+    readonly events?: EventTarget;
+    /**
+     * Broadcast channel. This is useful for communicating
+     * between tabs and windows (browser contexts).
+     *
+     * By default it does not use any broadcast channel.
+     * If a broadcast channel is provided, query
+     * won't close automatically, therefore, the responsability
+     * of closing the broadcast channel is up to the user.
+     */
+    readonly broadcast?: BroadcastChannel;
+}
+export interface FetcherAdditional {
+    /**
+     * An abort signal to cancel pending queries.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * The available options for query.
+ */
+export interface Options<T = unknown> {
+    /**
+     * Determines the item deduplication interval.
+     * This determines how many milliseconds an item
+     * is considered valid.
+     */
+    readonly expiration?: ExpirationFunction<T>;
+    /**
+     * Determines the fetcher function to use.
+     */
+    readonly fetcher?: FetcherFunction<T>;
+    /**
+     * Determines if we can return a stale item.
+     * If `true`, it will return the previous stale item
+     * stored in the cache if it has expired. It will attempt
+     * to revalidate it in the background. If `false`, the returned
+     * promise will be the revalidation promise.
+     */
+    readonly stale?: boolean;
+    /**
+     * Removes the stored item if there is an error in the request.
+     * By default, we don't remove the item upon failure, only the resolver
+     * is removed from the cache.
+     */
+    readonly removeOnError?: boolean;
+    /**
+     * Determines if the result should be a fresh fetched
+     * instance regardless of any cached value or its expiration time.
+     */
+    readonly fresh?: boolean;
+}
+/**
+ * The mutation function type.
+ */
+export type MutationFunction<T> = {
+    (previous?: T, expiresAt?: Date): T | Promise<T>;
+};
+/**
+ * The available mutation values.
+ */
+export type MutationValue<T> = T | MutationFunction<T>;
+/**
+ * The broadcast payload.
+ */
+export interface BroadcastPayload {
+    /**
+     * The event name.
+     */
+    readonly event: QueryEvent;
+    /**
+     * The event detail.
+     */
+    readonly detail: unknown;
+}
+/**
+ * The function type for the broadcast subscription.
+ */
+export type SubscribeBroadcastFunction = {
+    (): Unsubscriber;
+};
+/**
+ * The query function type.
+ */
+export type QueryFunction = {
+    <T = unknown>(key: string, options?: Options<T>): Promise<T>;
+};
+export type ExpirationFunction<T = unknown> = {
+    (item: T): number;
+};
+export type FetcherFunction<T = unknown> = {
+    (key: string, additional: FetcherAdditional): Promise<T>;
+};
+/**
+ * The mutate function options.
+ */
+export interface HydrateOptions<T = unknown> {
+    expiration?: ExpirationFunction<T>;
+}
+/**
+ * The mutate function options.
+ */
+export interface MutateOptions<T = unknown> {
+    expiration?: ExpirationFunction<T>;
+}
+/**
+ * The mutate function type.
+ */
+export type MutateFunction = {
+    <T = unknown>(key: string, item: MutationValue<T>, options?: MutateOptions<T>): Promise<T>;
+};
+/**
+ * The hydrate function type.
+ */
+export type HydrateFunction = {
+    <T = unknown>(keys: string | string[], item: T, options?: HydrateOptions<T>): void;
+};
+/**
+ * The unsubscriber function.
+ */
+export type Unsubscriber = () => void;
+export type OnceFunction = {
+    <T = unknown>(key: string, event: QueryEvent): Promise<CustomEventInit<T>>;
+};
+export type StreamFunction = {
+    <T = unknown>(key: string, event: QueryEvent): AsyncGenerator<CustomEventInit<T>>;
+};
+export type ConfigureFunction = {
+    (options?: Partial<Configuration>): void;
+};
+/**
+ * Represents the methods a query
+ * should implement.
+ */
+export interface Query {
+    /**
+     * Configures the current instance of query.
+     */
+    readonly configure: ConfigureFunction;
+    /**
+     * Fetches the key information using a fetcher.
+     * The returned promise contains the result item.
+     */
+    readonly query: QueryFunction;
+    /**
+     * Emit is able to send events to active subscribers
+     * with the given payload. It is a low level API
+     * and should be used with case.
+     */
+    readonly emit: EmitFunction;
+    /**
+     * Subscribes to a given event & key. The event handler
+     * does have a payload parameter that will contain relevant
+     * information depending on the event type.
+     */
+    readonly subscribe: SubscribeFunction;
+    /**
+     * Subscribes to the broadcast channel
+     * to listen for other browser context
+     * events and reproduce them in the current
+     * context.
+     */
+    readonly subscribeBroadcast: SubscribeBroadcastFunction;
+    /**
+     * Mutates the key with a given optimistic value.
+     * The mutated value is considered expired and will be
+     * replaced immediatly if a refetch happens.
+     */
+    readonly mutate: MutateFunction;
+    /**
+     * Aborts the active resolvers on each key
+     * by calling `.abort()` on the `AbortController`.
+     * The fetcher is responsible for using the
+     * `AbortSignal` to cancel the job.
+     */
+    readonly abort: (key?: string | string[], reason?: unknown) => void;
+    /**
+     * Forgets the given keys from the cache.
+     * Removes items from both, the cache and resolvers.
+     */
+    readonly forget: (keys?: string | string[] | RegExp) => Promise<void>;
+    /**
+     * Hydrates the given keys on the cache
+     * with the given value and expiration time.
+     */
+    readonly hydrate: HydrateFunction;
+    /**
+     * Returns the given keys for the given cache.
+     */
+    readonly keys: (cache?: CacheType) => string[];
+    /**
+     * Returns the expiration date of a given key item.
+     * If the item is not in the cache, it will return `undefined`.
+     */
+    readonly expiration: (key: string) => Date | undefined;
+    /**
+     * Returns the current snapshot of the given key.
+     * If the item is not in the items cache, it will return `undefined`.
+     */
+    readonly snapshot: <T = unknown>(key: string) => T | undefined;
+    /**
+     * Returns the first event on the given key that happens.
+     *
+     * It does so by subscribing and unsubscribing after event has
+     * been emitted.
+     */
+    readonly once: OnceFunction;
+    /**
+     * A generator that is able to stream events as they come in.
+     */
+    readonly stream: StreamFunction;
+    /**
+     * Returns the current cache instances in use.
+     */
+    readonly caches: () => Caches;
+    /**
+     * Returns the event system in use.
+     */
+    readonly events: () => EventTarget;
+    /**
+     * Returns the broadcast channel in use.
+     */
+    readonly broadcast: () => BroadcastChannel | undefined;
+}
+/**
+ * Available events on query.
+ */
+export type QueryEvent = 'refetching' | 'resolved' | 'mutating' | 'mutated' | 'aborted' | 'forgotten' | 'hydrated' | 'error';
+export type SubscribeListener<T> = (event: CustomEventInit<T>) => void;
+/**
+ * The function type for the event subscription.
+ */
+export interface SubscribeFunction {
+    <T = unknown>(key: string, event: 'refetching' | 'resolved' | 'mutating' | 'mutated' | 'forgotten' | 'hydrated', listener: SubscribeListener<Promise<T>>): Unsubscriber;
+    (key: string, event: 'error' | 'aborted', listener: SubscribeListener<unknown>): Unsubscriber;
+    <T = unknown>(key: string, event: QueryEvent, listener: SubscribeListener<T>): Unsubscriber;
+}
+/**
+ * The emit function to manually emit events.
+ */
+export interface EmitFunction {
+    <T = unknown>(key: string, event: 'refetching' | 'resolved' | 'mutating' | 'mutated' | 'forgotten' | 'hydrated', detail: Promise<T>): void;
+    (key: string, event: 'error' | 'aborted', detail: unknown): void;
+    <T = unknown>(key: string, event: QueryEvent, detail: T): void;
+}
+export type TriggerFunction = undefined | (() => Promise<void>);

package/dist/src/query/query.d.ts

@@ -0,0 +1,9 @@
+import { Configuration, FetcherFunction, Query } from './options';
+/**
+ * Stores the default fetcher function.
+ */
+export declare function defaultFetcher<T>(fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>): FetcherFunction<T>;
+/**
+ * Creates a new query instance.
+ */
+export declare function createQuery(instanceOptions?: Configuration): Query;

package/dist/src/react/components/QueryProvider.d.ts

@@ -1,9 +1,6 @@
 import { ReactNode } from 'react';
-import { ContextOptions } from '../context';
-import { Configuration } from '../../query/index';
-type OtherProps = Configuration & ContextOptions;
-export interface QueryProviderProps extends OtherProps {
+import { ContextValue } from '../context';
+export interface QueryProviderProps extends ContextValue {
     children?: ReactNode;
 }
-export declare function QueryProvider({ children, clearOnForget, broadcast, ...options }: QueryProviderProps): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function QueryProvider({ children, clearOnForget, ignoreTransitionContext, query, }: QueryProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/react/context.d.ts

@@ -1,10 +1,6 @@
-import { Query } from '../query/index';
-export interface ContextOptions {
+import { QueryInstance } from './hooks/useQueryInstance';
+export interface ContextValue extends QueryInstance {
     readonly clearOnForget?: boolean;
     readonly ignoreTransitionContext?: boolean;
 }
-export interface ContextValue {
-    readonly query?: Query;
-    readonly additional?: ContextOptions;
-}
 export declare const Context: import('react').Context<ContextValue>;

package/dist/src/react/hooks/useQuery.d.ts

@@ -1,13 +1,14 @@
-import { ContextOptions as ContextOptions } from '../context';
+import { ContextValue } from '../context';
 import { Options } from '../../query/index';
 import { QueryInstance } from './useQueryInstance';
 import { QueryActions } from './useQueryActions';
 import { Status } from './useQueryStatus';
-type AdditionalHooks<T> = QueryActions<T> & Status;
+import { BasicResource } from './useQueryBasic';
+type AdditionalHooks<T> = QueryActions<T> & BasicResource<T> & Status;
 export interface Resource<T = unknown> extends AdditionalHooks<T> {
     data: T;
     isPending: boolean;
 }
-export type ResourceOptions<T = unknown> = ContextOptions & Options<T> & QueryInstance;
+export type ResourceOptions<T = unknown> = ContextValue & Options<T> & QueryInstance;
 export declare function useQuery<T = unknown>(key: string, options?: ResourceOptions<T>): Resource<T>;
 export {};

package/dist/src/react/hooks/useQueryBasic.d.ts

@@ -0,0 +1,9 @@
+import { ContextValue } from '../context';
+import { Options } from '../../query/index';
+import { QueryInstance } from './useQueryInstance';
+export interface BasicResource<T = unknown> {
+    data: T;
+    isPending: boolean;
+}
+export type BasicResourceOptions<T = unknown> = ContextValue & Options<T> & QueryInstance;
+export declare function useQueryBasic<T = unknown>(key: string, options?: BasicResourceOptions<T>): BasicResource<T>;

package/dist/src/react/hooks/useQueryStatus.d.ts

@@ -1,7 +1,8 @@
+import { QueryInstance } from './useQueryInstance';
 export interface Status {
     readonly expiresAt: Date;
     readonly isExpired: boolean;
     readonly isRefetching: boolean;
     readonly isMutating: boolean;
 }
-export declare function useQueryStatus(key: string): Status;
+export declare function useQueryStatus(key: string, options?: QueryInstance): Status;

package/dist/src/react/index.d.ts

@@ -1,4 +1,5 @@
 export * from './hooks/useQuery';
+export * from './hooks/useQueryBasic';
 export * from './hooks/useQueryStatus';
 export * from './hooks/useQueryInstance';
 export * from './hooks/useQueryContext';

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@studiolambda/query",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "license": "MIT",
+  "keywords": [
+    "stale-while-revalidate",
+    "swr",
+    "react-query",
+    "isomorphic",
+    "fetch",
+    "query",
+    "data-management",
+    "ui",
+    "vanilla",
+    "react"
+  ],
   "description": "Lightweight, isomorphic and framework agnostic asynchronous data management for modern UIs",
   "author": {
     "name": "Erik C. Forés",
@@ -43,7 +55,7 @@
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "solid-js": "^1.9.0"
+    "solid-js": "^1.9.4"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -57,28 +69,28 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.10.2",
-    "@types/react": "19.0.1",
-    "@types/react-dom": "19.0.2",
-    "@typescript-eslint/eslint-plugin": "^8.18.0",
-    "@typescript-eslint/parser": "^8.18.0",
+    "@types/node": "^22.13.4",
+    "@types/react": "19.0.8",
+    "@types/react-dom": "19.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@typescript-eslint/parser": "^8.24.0",
     "@vitejs/plugin-react": "^4.3.4",
-    "@vitest/coverage-v8": "^2.1.8",
-    "@vitest/ui": "^2.1.8",
-    "eslint": "^9.16.0",
+    "@vitest/coverage-v8": "^3.0.5",
+    "@vitest/ui": "^3.0.5",
+    "eslint": "^9.20.1",
     "eslint-plugin-react-hooks": "^5.1.0",
-    "eslint-plugin-react-refresh": "^0.4.16",
+    "eslint-plugin-react-refresh": "^0.4.19",
     "eslint-plugin-solid": "^0.14.5",
-    "globals": "^15.13.0",
-    "happy-dom": "^15.11.7",
+    "globals": "^15.15.0",
+    "happy-dom": "^17.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "solid-js": "^1.9.3",
-    "typescript": "^5.7.2",
-    "typescript-eslint": "^8.18.0",
-    "vite": "^6.0.3",
-    "vite-plugin-dts": "^4.3.0",
-    "vite-plugin-solid": "^2.11.0",
-    "vitest": "^2.1.8"
+    "solid-js": "^1.9.4",
+    "typescript": "~5.7.3",
+    "typescript-eslint": "^8.24.0",
+    "vite": "^6.1.0",
+    "vite-plugin-dts": "^4.5.0",
+    "vite-plugin-solid": "^2.11.1",
+    "vitest": "^3.0.5"
   }
 }