@tanstack/lit-query 0.0.1 → 0.2.0

package/dist-cjs/createInfiniteQueryController.d.cts

@@ -0,0 +1,75 @@
+import { type DefaultError, type InfiniteData, type InfiniteQueryObserverOptions, type InfiniteQueryObserverResult, type QueryKey } from '@tanstack/query-core';
+import type { QueryClient } from '@tanstack/query-core';
+import type { ReactiveControllerHost } from 'lit' with { "resolution-mode": "import" };
+import { type Accessor, type ValueAccessor } from './accessor.cjs';
+/**
+ * Options accepted by `createInfiniteQueryController`.
+ *
+ * This is the Lit adapter shape for `InfiniteQueryObserverOptions`. Pass it
+ * directly or through an `Accessor` when the options depend on Lit host state.
+ */
+export type CreateInfiniteQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>;
+/**
+ * Accessor returned by `createInfiniteQueryController`.
+ *
+ * Call the accessor or read its `current` property to get the latest infinite
+ * query result. The attached methods delegate to the active infinite query
+ * observer.
+ */
+export type InfiniteQueryResultAccessor<TData, TError> = ValueAccessor<InfiniteQueryObserverResult<TData, TError>> & {
+    /** Refetches the current infinite query. */
+    refetch: InfiniteQueryObserverResult<TData, TError>['refetch'];
+    /** Fetches the next page for the current infinite query. */
+    fetchNextPage: InfiniteQueryObserverResult<TData, TError>['fetchNextPage'];
+    /** Fetches the previous page for the current infinite query. */
+    fetchPreviousPage: InfiniteQueryObserverResult<TData, TError>['fetchPreviousPage'];
+    /** Removes the controller from its Lit host and unsubscribes observers. */
+    destroy: () => void;
+};
+/**
+ * Creates a Lit reactive controller that subscribes the host to an infinite
+ * query.
+ *
+ * The returned accessor is callable and also exposes `current`, `refetch`,
+ * `fetchNextPage`, `fetchPreviousPage`, and `destroy`. When `options` is a
+ * function, it is re-read during host updates so query keys and options can
+ * follow reactive host state.
+ *
+ * If `queryClient` is omitted, the controller resolves the client from the
+ * nearest connected `QueryClientProvider`.
+ *
+ * @param host - The Lit reactive controller host that owns the infinite query
+ * subscription.
+ * @param options - Infinite query observer options, or a getter that returns
+ * options.
+ * @param queryClient - Optional explicit query client. Provide this for
+ * controllers that should not resolve a client from Lit context.
+ * @returns An accessor for the latest infinite query result with page helper
+ * methods.
+ *
+ * @example
+ * ```ts
+ * import { LitElement, html } from 'lit'
+ * import { createInfiniteQueryController } from '@tanstack/lit-query'
+ *
+ * class ProjectsView extends LitElement {
+ *   private readonly projects = createInfiniteQueryController(this, {
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextCursor,
+ *   })
+ *
+ *   render() {
+ *     const query = this.projects()
+ *
+ *     return html`
+ *       <button ?disabled=${!query.hasNextPage} @click=${() => this.projects.fetchNextPage()}>
+ *         Load more
+ *       </button>
+ *     `
+ *   }
+ * }
+ * ```
+ */
+export declare function createInfiniteQueryController<TQueryFnData = unknown, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(host: ReactiveControllerHost, options: Accessor<CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>, queryClient?: QueryClient): InfiniteQueryResultAccessor<TData, TError>;

package/dist-cjs/createInfiniteQueryController.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInfiniteQueryController = createInfiniteQueryController;
+const query_core_1 = require("@tanstack/query-core");
+const accessor_js_1 = require("./accessor.js");
+const context_js_1 = require("./context.js");
+const BaseController_js_1 = require("./controllers/BaseController.js");
+function createPendingInfiniteQueryResult() {
+    return {
+        data: undefined,
+        dataUpdatedAt: 0,
+        error: null,
+        errorUpdatedAt: 0,
+        failureCount: 0,
+        failureReason: null,
+        errorUpdateCount: 0,
+        isError: false,
+        isFetched: false,
+        isFetchedAfterMount: false,
+        isFetching: false,
+        isInitialLoading: false,
+        isLoading: false,
+        isLoadingError: false,
+        isPaused: false,
+        isPending: true,
+        isPlaceholderData: false,
+        isRefetchError: false,
+        isRefetching: false,
+        isStale: true,
+        isEnabled: true,
+        isSuccess: false,
+        fetchStatus: 'idle',
+        status: 'pending',
+        refetch: (() => Promise.reject((0, context_js_1.createMissingQueryClientError)())),
+        fetchNextPage: (() => Promise.reject((0, context_js_1.createMissingQueryClientError)())),
+        fetchPreviousPage: (() => Promise.reject((0, context_js_1.createMissingQueryClientError)())),
+        hasNextPage: false,
+        hasPreviousPage: false,
+        isFetchNextPageError: false,
+        isFetchingNextPage: false,
+        isFetchPreviousPageError: false,
+        isFetchingPreviousPage: false,
+        promise: Promise.resolve(undefined),
+    };
+}
+class InfiniteQueryController extends BaseController_js_1.BaseController {
+    options;
+    observer;
+    unsubscribe;
+    queryClient;
+    constructor(host, options, queryClient) {
+        super(host, createPendingInfiniteQueryResult(), queryClient);
+        this.options = options;
+        if (!queryClient) {
+            return;
+        }
+        if (typeof options === 'function') {
+            return;
+        }
+        const defaulted = this.defaultOptions(queryClient);
+        const observer = new query_core_1.InfiniteQueryObserver(queryClient, defaulted);
+        this.queryClient = queryClient;
+        this.observer = observer;
+        this.result = observer.getOptimisticResult(defaulted);
+    }
+    onConnected() {
+        if (!this.syncClient()) {
+            return;
+        }
+        this.refreshOptions();
+        this.subscribe();
+        this.observer?.updateResult();
+        if (this.observer) {
+            this.setResult(this.observer.getCurrentResult());
+        }
+    }
+    onDisconnected() {
+        this.unsubscribeObserver();
+        this.syncClient();
+    }
+    onHostUpdate() {
+        if (typeof this.options !== 'function') {
+            return;
+        }
+        this.refreshOptions();
+    }
+    onQueryClientChanged() {
+        if (!this.syncClient() || !this.connectedState) {
+            return;
+        }
+        this.refreshOptions();
+        this.subscribe();
+        this.observer?.updateResult();
+        if (this.observer) {
+            this.setResult(this.observer.getCurrentResult());
+        }
+    }
+    refetch = (...args) => {
+        if (!this.refreshOptions()) {
+            return Promise.reject((0, context_js_1.createMissingQueryClientError)());
+        }
+        return this.result.refetch(...args);
+    };
+    fetchNextPage = (...args) => {
+        if (!this.refreshOptions()) {
+            return Promise.reject((0, context_js_1.createMissingQueryClientError)());
+        }
+        return this.result.fetchNextPage(...args);
+    };
+    fetchPreviousPage = (...args) => {
+        if (!this.refreshOptions()) {
+            return Promise.reject((0, context_js_1.createMissingQueryClientError)());
+        }
+        return this.result.fetchPreviousPage(...args);
+    };
+    subscribe() {
+        if (!this.observer) {
+            return;
+        }
+        if (this.unsubscribe) {
+            return;
+        }
+        this.unsubscribe = this.observer.subscribe((next) => {
+            this.setResult(next);
+        });
+    }
+    unsubscribeObserver() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    syncClient() {
+        const nextClient = this.tryGetQueryClient();
+        if (!nextClient) {
+            this.unsubscribeObserver();
+            this.queryClient = undefined;
+            this.observer = undefined;
+            this.setResult(createPendingInfiniteQueryResult());
+            return false;
+        }
+        if (nextClient === this.queryClient) {
+            return true;
+        }
+        this.unsubscribeObserver();
+        this.queryClient = nextClient;
+        const options = this.defaultOptions(this.queryClient);
+        this.observer = new query_core_1.InfiniteQueryObserver(this.queryClient, options);
+        this.setResult(this.observer.getOptimisticResult(options));
+        return true;
+    }
+    refreshOptions() {
+        if (!this.syncClient() || !this.observer || !this.queryClient) {
+            return false;
+        }
+        const options = this.defaultOptions(this.queryClient);
+        this.observer.setOptions(options);
+        this.setResult(this.observer.getOptimisticResult(options));
+        return true;
+    }
+    defaultOptions(client = this.queryClient) {
+        if (!client) {
+            throw (0, context_js_1.createMissingQueryClientError)();
+        }
+        const defaulted = client.defaultQueryOptions((0, accessor_js_1.readAccessor)(this.options));
+        defaulted._optimisticResults =
+            'optimistic';
+        return defaulted;
+    }
+}
+/**
+ * Creates a Lit reactive controller that subscribes the host to an infinite
+ * query.
+ *
+ * The returned accessor is callable and also exposes `current`, `refetch`,
+ * `fetchNextPage`, `fetchPreviousPage`, and `destroy`. When `options` is a
+ * function, it is re-read during host updates so query keys and options can
+ * follow reactive host state.
+ *
+ * If `queryClient` is omitted, the controller resolves the client from the
+ * nearest connected `QueryClientProvider`.
+ *
+ * @param host - The Lit reactive controller host that owns the infinite query
+ * subscription.
+ * @param options - Infinite query observer options, or a getter that returns
+ * options.
+ * @param queryClient - Optional explicit query client. Provide this for
+ * controllers that should not resolve a client from Lit context.
+ * @returns An accessor for the latest infinite query result with page helper
+ * methods.
+ *
+ * @example
+ * ```ts
+ * import { LitElement, html } from 'lit'
+ * import { createInfiniteQueryController } from '@tanstack/lit-query'
+ *
+ * class ProjectsView extends LitElement {
+ *   private readonly projects = createInfiniteQueryController(this, {
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextCursor,
+ *   })
+ *
+ *   render() {
+ *     const query = this.projects()
+ *
+ *     return html`
+ *       <button ?disabled=${!query.hasNextPage} @click=${() => this.projects.fetchNextPage()}>
+ *         Load more
+ *       </button>
+ *     `
+ *   }
+ * }
+ * ```
+ */
+function createInfiniteQueryController(host, options, queryClient) {
+    const controller = new InfiniteQueryController(host, options, queryClient);
+    return Object.assign((0, accessor_js_1.createValueAccessor)(() => controller.current), {
+        refetch: controller.refetch,
+        fetchNextPage: controller.fetchNextPage,
+        fetchPreviousPage: controller.fetchPreviousPage,
+        destroy: () => controller.destroy(),
+    });
+}
+//# sourceMappingURL=createInfiniteQueryController.js.map

package/dist-cjs/createInfiniteQueryController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createInfiniteQueryController.js","sourceRoot":"","sources":["../src/createInfiniteQueryController.ts"],"names":[],"mappings":";;AA2WA,sEA8BC;AAzYD,qDAQ6B;AAG7B,+CAKsB;AACtB,6CAA4D;AAC5D,uEAAgE;AA6ChE,SAAS,gCAAgC;IAIvC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,aAAa,EAAE,CAAC;QAChB,KAAK,EAAE,IAAI;QACX,cAAc,EAAE,CAAC;QACjB,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,IAAI;QACnB,gBAAgB,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK;QACd,SAAS,EAAE,KAAK;QAChB,mBAAmB,EAAE,KAAK;QAC1B,UAAU,EAAE,KAAK;QACjB,gBAAgB,EAAE,KAAK;QACvB,SAAS,EAAE,KAAK;QAChB,cAAc,EAAE,KAAK;QACrB,QAAQ,EAAE,KAAK;QACf,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,KAAK;QACxB,cAAc,EAAE,KAAK;QACrB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,KAAK;QAChB,WAAW,EAAE,MAAM;QACnB,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,CAAC,GAAG,EAAE,CACb,OAAO,CAAC,MAAM,CACZ,IAAA,0CAA6B,GAAE,CAChC,CAA0D;QAC7D,aAAa,EAAE,CAAC,GAAG,EAAE,CACnB,OAAO,CAAC,MAAM,CACZ,IAAA,0CAA6B,GAAE,CAChC,CAAgE;QACnE,iBAAiB,EAAE,CAAC,GAAG,EAAE,CACvB,OAAO,CAAC,MAAM,CACZ,IAAA,0CAA6B,GAAE,CAChC,CAAoE;QACvE,WAAW,EAAE,KAAK;QAClB,eAAe,EAAE,KAAK;QACtB,oBAAoB,EAAE,KAAK;QAC3B,kBAAkB,EAAE,KAAK;QACzB,wBAAwB,EAAE,KAAK;QAC/B,sBAAsB,EAAE,KAAK;QAC7B,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,SAAkB,CAAC;KACY,CAAA;AAC5D,CAAC;AAED,MAAM,uBAMJ,SAAQ,kCAA0D;IACjD,OAAO,CAQvB;IACO,QAAQ,CAEH;IACL,WAAW,CAA0B;IACrC,WAAW,CAAyB;IAE5C,YACE,IAA4B,EAC5B,OAQC,EACD,WAAyB;QAEzB,KAAK,CAAC,IAAI,EAAE,gCAAgC,EAAE,EAAE,WAAW,CAAC,CAAA;QAC5D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtB,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAM;QACR,CAAC;QAED,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAClC,OAAM;QACR,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,CAAA;QAClD,MAAM,QAAQ,GAAG,IAAI,kCAAqB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;QAClE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAA;IACvD,CAAC;IAES,WAAW;QACnB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YACvB,OAAM;QACR,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAA;QACrB,IAAI,CAAC,SAAS,EAAE,CAAA;QAChB,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;QAC7B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAA;QAClD,CAAC;IACH,CAAC;IAES,cAAc;QACtB,IAAI,CAAC,mBAAmB,EAAE,CAAA;QAC1B,IAAI,CAAC,UAAU,EAAE,CAAA;IACnB,CAAC;IAES,YAAY;QACpB,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACvC,OAAM;QACR,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAA;IACvB,CAAC;IAES,oBAAoB;QAC5B,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YAC/C,OAAM;QACR,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAA;QACrB,IAAI,CAAC,SAAS,EAAE,CAAA;QAChB,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;QAC7B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAA;QAClD,CAAC;IACH,CAAC;IAED,OAAO,GAA0D,CAC/D,GAAG,IAAI,EACP,EAAE;QACF,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAA,0CAA6B,GAAE,CAAC,CAAA;QACxD,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;IACrC,CAAC,CAAA;IAED,aAAa,GAAgE,CAC3E,GAAG,IAAI,EACP,EAAE;QACF,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAA,0CAA6B,GAAE,CAAC,CAAA;QACxD,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,CAAA;IAC3C,CAAC,CAAA;IAED,iBAAiB,GAGQ,CAAC,GAAG,IAAI,EAAE,EAAE;QACnC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAA,0CAA6B,GAAE,CAAC,CAAA;QACxD,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,CAAA;IAC/C,CAAC,CAAA;IAEO,SAAS;QACf,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAM;QACR,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAM;QACR,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACtB,CAAC,CAAC,CAAA;IACJ,CAAC;IAEO,mBAAmB;QACzB,IAAI,CAAC,WAAW,EAAE,EAAE,CAAA;QACpB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;IAC9B,CAAC;IAEO,UAAU;QAChB,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAA;QAC3C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC,mBAAmB,EAAE,CAAA;YAC1B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;YAC5B,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAA;YACzB,IAAI,CAAC,SAAS,CAAC,gCAAgC,EAAE,CAAC,CAAA;YAClD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,UAAU,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YACpC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,mBAAmB,EAAE,CAAA;QAC1B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QACrD,IAAI,CAAC,QAAQ,GAAG,IAAI,kCAAqB,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACpE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAA;QAC1D,OAAO,IAAI,CAAA;IACb,CAAC;IAEO,cAAc;QACpB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAC9D,OAAO,KAAK,CAAA;QACd,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QACrD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;QACjC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAA;QAC1D,OAAO,IAAI,CAAA;IACb,CAAC;IAEO,cAAc,CACpB,MAAM,GAAG,IAAI,CAAC,WAAW;QAQzB,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAA,0CAA6B,GAAE,CAAA;QACvC,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,mBAAmB,CAC1C,IAAA,0BAAY,EAAC,IAAI,CAAC,OAAO,CAAC,CAO3B,CACA;QAAC,SAAmD,CAAC,kBAAkB;YACtE,YAAY,CAAA;QACd,OAAO,SAAS,CAAA;IAClB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,SAAgB,6BAA6B,CAO3C,IAA4B,EAC5B,OAQC,EACD,WAAyB;IAEzB,MAAM,UAAU,GAAG,IAAI,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAAA;IAE1E,OAAO,MAAM,CAAC,MAAM,CAClB,IAAA,iCAAmB,EAAC,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAC7C;QACE,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,iBAAiB,EAAE,UAAU,CAAC,iBAAiB;QAC/C,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE;KACpC,CACF,CAAA;AACH,CAAC"}

package/dist-cjs/createMutationController.d.cts

@@ -0,0 +1,78 @@
+import { type DefaultError, type MutateOptions, type MutationObserverOptions, type MutationObserverResult } from '@tanstack/query-core';
+import type { QueryClient } from '@tanstack/query-core';
+import type { ReactiveControllerHost } from 'lit' with { "resolution-mode": "import" };
+import { type Accessor, type ValueAccessor } from './accessor.cjs';
+/**
+ * Options accepted by `createMutationController`.
+ *
+ * This is the Lit adapter shape for `MutationObserverOptions`. Pass it directly
+ * or through an `Accessor` when the options depend on Lit host state.
+ */
+export type CreateMutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>;
+/**
+ * Accessor returned by `createMutationController`.
+ *
+ * Call the accessor or read its `current` property to get the latest mutation
+ * result. The attached methods delegate to the active mutation observer.
+ */
+export type MutationResultAccessor<TData, TError, TVariables, TOnMutateResult> = ValueAccessor<MutationObserverResult<TData, TError, TVariables, TOnMutateResult>> & {
+    /**
+     * Starts the mutation and swallows the returned promise.
+     *
+     * Throws synchronously if no `QueryClient` can be resolved.
+     */
+    mutate: (variables: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>) => void;
+    /**
+     * Starts the mutation and returns the observer promise.
+     *
+     * Rejects if no `QueryClient` can be resolved.
+     */
+    mutateAsync: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>['mutate'];
+    /** Resets the mutation observer to its idle state. */
+    reset: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>['reset'];
+    /** Removes the controller from its Lit host and unsubscribes observers. */
+    destroy: () => void;
+};
+/**
+ * Creates a Lit reactive controller that subscribes the host to a mutation.
+ *
+ * The returned accessor is callable and also exposes `current`, `mutate`,
+ * `mutateAsync`, `reset`, and `destroy`. When `options` is a function, it is
+ * re-read during host updates so mutation options can follow reactive host
+ * state.
+ *
+ * If `queryClient` is omitted, the controller resolves the client from the
+ * nearest connected `QueryClientProvider`.
+ *
+ * @param host - The Lit reactive controller host that owns the mutation
+ * subscription.
+ * @param options - Mutation observer options, or a getter that returns options.
+ * @param queryClient - Optional explicit query client. Provide this for
+ * controllers that should not resolve a client from Lit context.
+ * @returns An accessor for the latest mutation result with mutation helper
+ * methods.
+ *
+ * @example
+ * ```ts
+ * import { LitElement, html } from 'lit'
+ * import { createMutationController } from '@tanstack/lit-query'
+ *
+ * class AddTodoForm extends LitElement {
+ *   private readonly addTodo = createMutationController(this, {
+ *     mutationFn: (title: string) =>
+ *       fetch('/api/todos', { method: 'POST', body: JSON.stringify({ title }) }),
+ *   })
+ *
+ *   render() {
+ *     const mutation = this.addTodo()
+ *
+ *     return html`
+ *       <button ?disabled=${mutation.isPending} @click=${() => this.addTodo.mutate('Ship docs')}>
+ *         Add todo
+ *       </button>
+ *     `
+ *   }
+ * }
+ * ```
+ */
+export declare function createMutationController<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(host: ReactiveControllerHost, options: Accessor<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>>, queryClient?: QueryClient): MutationResultAccessor<TData, TError, TVariables, TOnMutateResult>;

package/dist-cjs/createMutationController.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMutationController = createMutationController;
+const query_core_1 = require("@tanstack/query-core");
+const accessor_js_1 = require("./accessor.js");
+const context_js_1 = require("./context.js");
+const BaseController_js_1 = require("./controllers/BaseController.js");
+function createIdleMutationResult() {
+    return {
+        context: undefined,
+        data: undefined,
+        error: null,
+        failureCount: 0,
+        failureReason: null,
+        isError: false,
+        isIdle: true,
+        isPending: false,
+        isPaused: false,
+        isSuccess: false,
+        status: 'idle',
+        submittedAt: 0,
+        variables: undefined,
+        mutate: (() => Promise.reject((0, context_js_1.createMissingQueryClientError)())),
+        reset: (() => undefined),
+    };
+}
+class MutationController extends BaseController_js_1.BaseController {
+    options;
+    observer;
+    unsubscribe;
+    queryClient;
+    constructor(host, options, queryClient) {
+        super(host, createIdleMutationResult(), queryClient);
+        this.options = options;
+        if (!queryClient) {
+            return;
+        }
+        if (typeof options === 'function') {
+            return;
+        }
+        const observer = new query_core_1.MutationObserver(queryClient, this.defaultOptions(queryClient));
+        this.queryClient = queryClient;
+        this.observer = observer;
+        this.result = observer.getCurrentResult();
+    }
+    onConnected() {
+        if (!this.syncClient()) {
+            return;
+        }
+        this.refreshOptions();
+        this.subscribe();
+        if (this.observer) {
+            this.setResult(this.observer.getCurrentResult());
+        }
+    }
+    onDisconnected() {
+        this.unsubscribeObserver();
+        this.syncClient();
+    }
+    onHostUpdate() {
+        if (typeof this.options !== 'function') {
+            return;
+        }
+        this.refreshOptions();
+    }
+    onQueryClientChanged() {
+        if (!this.syncClient() || !this.connectedState) {
+            return;
+        }
+        this.refreshOptions();
+        this.subscribe();
+        if (this.observer) {
+            this.setResult(this.observer.getCurrentResult());
+        }
+    }
+    mutate = (variables, mutateOptions) => {
+        if (!this.syncClient() || !this.observer) {
+            throw (0, context_js_1.createMissingQueryClientError)();
+        }
+        void this.observer.mutate(variables, mutateOptions).catch(() => {
+            // Intentionally swallow in sync mutate path.
+        });
+    };
+    mutateAsync = (...args) => {
+        if (!this.syncClient() || !this.observer) {
+            return Promise.reject((0, context_js_1.createMissingQueryClientError)());
+        }
+        return this.observer.mutate(...args);
+    };
+    reset = () => {
+        if (!this.syncClient() || !this.observer) {
+            return;
+        }
+        this.observer.reset();
+        this.setResult(this.observer.getCurrentResult());
+    };
+    subscribe() {
+        if (!this.observer) {
+            return;
+        }
+        if (this.unsubscribe) {
+            return;
+        }
+        this.unsubscribe = this.observer.subscribe((next) => {
+            this.setResult(next);
+        });
+    }
+    unsubscribeObserver() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    syncClient() {
+        const nextClient = this.tryGetQueryClient();
+        if (!nextClient) {
+            this.unsubscribeObserver();
+            this.queryClient = undefined;
+            this.observer = undefined;
+            this.setResult(createIdleMutationResult());
+            return false;
+        }
+        if (nextClient === this.queryClient) {
+            return true;
+        }
+        this.unsubscribeObserver();
+        this.queryClient = nextClient;
+        this.observer = new query_core_1.MutationObserver(this.queryClient, this.defaultOptions(this.queryClient));
+        this.setResult(this.observer.getCurrentResult());
+        return true;
+    }
+    refreshOptions() {
+        if (!this.syncClient() || !this.observer || !this.queryClient) {
+            return false;
+        }
+        this.observer.setOptions(this.defaultOptions());
+        this.setResult(this.observer.getCurrentResult());
+        return true;
+    }
+    defaultOptions(client = this.queryClient) {
+        if (!client) {
+            throw (0, context_js_1.createMissingQueryClientError)();
+        }
+        return client.defaultMutationOptions((0, accessor_js_1.readAccessor)(this.options));
+    }
+}
+/**
+ * Creates a Lit reactive controller that subscribes the host to a mutation.
+ *
+ * The returned accessor is callable and also exposes `current`, `mutate`,
+ * `mutateAsync`, `reset`, and `destroy`. When `options` is a function, it is
+ * re-read during host updates so mutation options can follow reactive host
+ * state.
+ *
+ * If `queryClient` is omitted, the controller resolves the client from the
+ * nearest connected `QueryClientProvider`.
+ *
+ * @param host - The Lit reactive controller host that owns the mutation
+ * subscription.
+ * @param options - Mutation observer options, or a getter that returns options.
+ * @param queryClient - Optional explicit query client. Provide this for
+ * controllers that should not resolve a client from Lit context.
+ * @returns An accessor for the latest mutation result with mutation helper
+ * methods.
+ *
+ * @example
+ * ```ts
+ * import { LitElement, html } from 'lit'
+ * import { createMutationController } from '@tanstack/lit-query'
+ *
+ * class AddTodoForm extends LitElement {
+ *   private readonly addTodo = createMutationController(this, {
+ *     mutationFn: (title: string) =>
+ *       fetch('/api/todos', { method: 'POST', body: JSON.stringify({ title }) }),
+ *   })
+ *
+ *   render() {
+ *     const mutation = this.addTodo()
+ *
+ *     return html`
+ *       <button ?disabled=${mutation.isPending} @click=${() => this.addTodo.mutate('Ship docs')}>
+ *         Add todo
+ *       </button>
+ *     `
+ *   }
+ * }
+ * ```
+ */
+function createMutationController(host, options, queryClient) {
+    const controller = new MutationController(host, options, queryClient);
+    return Object.assign((0, accessor_js_1.createValueAccessor)(() => controller.current), {
+        mutate: controller.mutate,
+        mutateAsync: controller.mutateAsync,
+        reset: controller.reset,
+        destroy: () => controller.destroy(),
+    });
+}
+//# sourceMappingURL=createMutationController.js.map

package/dist-cjs/createMutationController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMutationController.js","sourceRoot":"","sources":["../src/createMutationController.ts"],"names":[],"mappings":"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"}