@freecorps/ember-react-query 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @freecorps/ember-react-query
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TanStack Query integration for Ember: emberQuery() and live query updates.
+
+Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
+Objects. Source: [`packages/react-query`](https://github.com/freecorps/ember/tree/main/packages/react-query).
+
+```sh
+npm install @freecorps/ember-react-query
+```
+
+License: MIT.

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { type QueryClient, type QueryKey } from "@tanstack/react-query";
+import { EmberError, type EmberClient, type FunctionReference, type MutationOptions, type ShardOptions } from "@freecorps/ember-client";
+type QueryRef = FunctionReference<"query"> | string;
+type MutationRef = FunctionReference<"mutation"> | string;
+type ArgsOf<F> = F extends FunctionReference<any, infer A, any> ? A : Record<string, unknown>;
+type ReturnOf<F> = F extends FunctionReference<any, any, infer R> ? R : unknown;
+/** `["ember", shard | null, "module:export", args]`; a null shard means the client's `defaultShard`. */
+export type EmberQueryKey = readonly ["ember", string | null, string, Record<string, unknown> | "skip"];
+export declare const isEmberQueryKey: (key: QueryKey) => key is EmberQueryKey;
+/** Hash for TanStack: ember keys via the tagged stable JSON (bigint/bytes safe), others via `hashKey`. */
+export declare function emberQueryKeyHashFn(key: QueryKey): string;
+/**
+ * Query options for `useQuery`, `useSuspenseQuery`, `prefetchQuery`, ... `"skip"` disables the query.
+ */
+export declare function emberQuery<Q extends QueryRef>(ref: Q, args?: ArgsOf<Q> | "skip", opts?: ShardOptions): import("@tanstack/react-query").UseQueryOptions<ReturnOf<Q>, EmberError, ReturnOf<Q>, EmberQueryKey> & {
+    initialData?: import("@tanstack/react-query").NonUndefinedGuard<ReturnOf<Q>> | import("@tanstack/react-query").InitialDataFunction<import("@tanstack/react-query").NonUndefinedGuard<ReturnOf<Q>>> | undefined;
+} & import("@tanstack/react-query").QueryKeyWithDataTag<EmberQueryKey, ReturnOf<Q>, EmberError>;
+/**
+ * Same key as `emberQuery`, fetched once over HTTP (`POST /api/query`) with the given client. For SSR / loaders:
+ * `await queryClient.prefetchQuery(emberQueryOneShot(ember, api.x.y, args))`, dehydrate, hydrate in the browser;
+ * the live subscription starts when a component observes the query.
+ */
+export declare function emberQueryOneShot<Q extends QueryRef>(client: EmberClient, ref: Q, args?: ArgsOf<Q>, opts?: ShardOptions): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<ReturnOf<Q>, EmberError, ReturnOf<Q>, EmberQueryKey>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<ReturnOf<Q>, EmberQueryKey, never>;
+} & import("@tanstack/react-query").QueryKeyWithDataTag<EmberQueryKey, ReturnOf<Q>, EmberError>;
+/** `prefetchQuery` over HTTP (no socket): the SSR helper. */
+export declare function prefetchEmberQuery<Q extends QueryRef>(queryClient: QueryClient, client: EmberClient, ref: Q, args?: ArgsOf<Q>, opts?: ShardOptions): Promise<void>;
+/**
+ * `mutationFn` for `useMutation`. Runs over the EmberQueryClient connected to the mutation's QueryClient; the
+ * optimistic update (if any) flows into the TanStack cache through the live queries.
+ */
+export declare function emberMutationFn<M extends MutationRef>(ref: M, opts?: MutationOptions<ArgsOf<M>>): (variables: ArgsOf<M>, context: {
+    client: QueryClient;
+}) => Promise<ReturnOf<M>>;
+export interface EmberQueryClientOptions {
+    /** Fetch with HTTP one-shots and never subscribe (SSR). Default: true when there is no `window`. */
+    ssr?: boolean;
+}
+export declare class EmberQueryClient {
+    readonly client: EmberClient;
+    private queryClient;
+    private stopCache;
+    private readonly live;
+    private readonly ssr;
+    constructor(client: EmberClient, options?: EmberQueryClientOptions);
+    /** Attach to a QueryClient: sets the ember-aware key hash and starts following its cache. */
+    connect(queryClient: QueryClient): this;
+    disconnect(): void;
+    /** Number of live subscriptions held for the TanStack cache. */
+    get subscriptionCount(): number;
+    private target;
+    /** queryFn for ember keys: the live value if there is one, else the first snapshot (or HTTP in SSR). */
+    fetch(key: QueryKey): Promise<unknown>;
+    private onCacheEvent;
+    private watch;
+    private unwatch;
+    private push;
+}
+export { EmberError };

package/dist/index.js

@@ -0,0 +1,181 @@
+// TanStack Query adapter for @freecorps/ember-client (in the spirit of @convex-dev/react-query).
+//
+//   const ember = new EmberClient({ url, defaultShard: "org:acme" });
+//   const queryClient = new QueryClient();
+//   new EmberQueryClient(ember).connect(queryClient);
+//
+//   const { data } = useQuery(emberQuery(api.messages.list, { channel }));
+//   const send = useMutation({ mutationFn: emberMutationFn(api.messages.send) });
+//
+// Queries live in the TanStack cache under ["ember", shard, fn, args] with staleTime Infinity. A query is
+// subscribed over the socket while it has observers and until TanStack garbage-collects it (gcTime); every server
+// patch (and optimistic update) is pushed with setQueryData.
+import { hashKey, queryOptions, skipToken } from "@tanstack/react-query";
+import { EmberError, getFunctionName, stableStringify, } from "@freecorps/ember-client";
+export const isEmberQueryKey = (key) => key[0] === "ember" && key.length === 4 && typeof key[2] === "string";
+/** Hash for TanStack: ember keys via the tagged stable JSON (bigint/bytes safe), others via `hashKey`. */
+export function emberQueryKeyHashFn(key) {
+    return isEmberQueryKey(key) ? `ember:${stableStringify(key)}` : hashKey(key);
+}
+const registry = new WeakMap();
+function connected(qc) {
+    const e = registry.get(qc);
+    if (!e)
+        throw new Error("Ember: this QueryClient is not connected (new EmberQueryClient(client).connect(queryClient))");
+    return e;
+}
+/**
+ * Query options for `useQuery`, `useSuspenseQuery`, `prefetchQuery`, ... `"skip"` disables the query.
+ */
+export function emberQuery(ref, args = {}, opts) {
+    const key = ["ember", opts?.shard ?? null, getFunctionName(ref), args === "skip" ? "skip" : (args ?? {})];
+    return queryOptions({
+        queryKey: key,
+        queryFn: args === "skip" ? skipToken : (ctx) => connected(ctx.client).fetch(ctx.queryKey),
+        queryKeyHashFn: emberQueryKeyHashFn,
+        staleTime: Infinity,
+    });
+}
+/**
+ * Same key as `emberQuery`, fetched once over HTTP (`POST /api/query`) with the given client. For SSR / loaders:
+ * `await queryClient.prefetchQuery(emberQueryOneShot(ember, api.x.y, args))`, dehydrate, hydrate in the browser;
+ * the live subscription starts when a component observes the query.
+ */
+export function emberQueryOneShot(client, ref, args = {}, opts) {
+    const base = emberQuery(ref, args, opts);
+    return queryOptions({
+        ...base,
+        queryFn: () => client.query(ref, args, opts),
+    });
+}
+/** `prefetchQuery` over HTTP (no socket): the SSR helper. */
+export function prefetchEmberQuery(queryClient, client, ref, args, opts) {
+    return queryClient.prefetchQuery(emberQueryOneShot(client, ref, args, opts));
+}
+/**
+ * `mutationFn` for `useMutation`. Runs over the EmberQueryClient connected to the mutation's QueryClient; the
+ * optimistic update (if any) flows into the TanStack cache through the live queries.
+ */
+export function emberMutationFn(ref, opts) {
+    return (variables, context) => connected(context.client).client.mutation(ref, variables, opts);
+}
+export class EmberQueryClient {
+    client;
+    queryClient = null;
+    stopCache = null;
+    live = new Map();
+    ssr;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.ssr = options.ssr ?? typeof globalThis.window === "undefined";
+    }
+    /** Attach to a QueryClient: sets the ember-aware key hash and starts following its cache. */
+    connect(queryClient) {
+        if (this.queryClient)
+            throw new Error("EmberQueryClient is already connected");
+        this.queryClient = queryClient;
+        registry.set(queryClient, this);
+        const defaults = queryClient.getDefaultOptions();
+        queryClient.setDefaultOptions({ ...defaults, queries: { ...defaults.queries, queryKeyHashFn: emberQueryKeyHashFn } });
+        this.stopCache = queryClient.getQueryCache().subscribe((e) => this.onCacheEvent(e));
+        for (const q of queryClient.getQueryCache().getAll())
+            if (q.getObserversCount() > 0)
+                this.watch(q);
+        return this;
+    }
+    disconnect() {
+        this.stopCache?.();
+        this.stopCache = null;
+        for (const l of this.live.values())
+            l.off();
+        this.live.clear();
+        if (this.queryClient)
+            registry.delete(this.queryClient);
+        this.queryClient = null;
+    }
+    /** Number of live subscriptions held for the TanStack cache. */
+    get subscriptionCount() {
+        return this.live.size;
+    }
+    target(key) {
+        const [, shard, fn, args] = key;
+        return { fn, args: args === "skip" ? {} : args, opts: shard === null ? undefined : { shard } };
+    }
+    /** queryFn for ember keys: the live value if there is one, else the first snapshot (or HTTP in SSR). */
+    fetch(key) {
+        if (!isEmberQueryKey(key) || key[3] === "skip")
+            return Promise.reject(new Error("Ember: not an ember query key"));
+        const { fn, args, opts } = this.target(key);
+        if (this.ssr)
+            return this.client.query(fn, args, opts);
+        const now = this.client.localQueryResult(fn, args, opts);
+        if (now.status === "success")
+            return Promise.resolve(now.value);
+        return new Promise((resolve, reject) => {
+            let off = null;
+            let settled = false;
+            const done = (s) => {
+                if (settled || s.status === "loading")
+                    return;
+                settled = true;
+                // unsubscribe after the current dispatch; the observer's live subscription (if any) keeps the server sub
+                queueMicrotask(() => off?.());
+                if (s.status === "success")
+                    resolve(s.value);
+                else
+                    reject(s.error);
+            };
+            off = this.client.subscribe(fn, args, opts, done);
+            if (settled)
+                off();
+        });
+    }
+    onCacheEvent(e) {
+        if (!isEmberQueryKey(e.query.queryKey))
+            return;
+        if (e.type === "observerAdded")
+            this.watch(e.query);
+        else if (e.type === "removed")
+            this.unwatch(e.query.queryHash);
+    }
+    watch(query) {
+        if (this.ssr || this.live.has(query.queryHash))
+            return;
+        const key = query.queryKey;
+        if (key[3] === "skip")
+            return;
+        const { fn, args, opts } = this.target(key);
+        const hash = query.queryHash;
+        const off = this.client.subscribe(fn, args, opts, (s) => this.push(hash, s));
+        this.live.set(hash, { off, query });
+    }
+    unwatch(hash) {
+        const l = this.live.get(hash);
+        if (!l)
+            return;
+        this.live.delete(hash);
+        l.off();
+    }
+    push(hash, s) {
+        const l = this.live.get(hash);
+        const qc = this.queryClient;
+        if (!l || !qc)
+            return;
+        if (s.status === "success") {
+            qc.setQueryData(l.query.queryKey, s.value);
+        }
+        else if (s.status === "error" && s.error) {
+            const st = l.query.state;
+            l.query.setState({
+                status: "error",
+                fetchStatus: "idle",
+                error: s.error,
+                errorUpdateCount: st.errorUpdateCount + 1,
+                errorUpdatedAt: Date.now(),
+                fetchFailureCount: st.fetchFailureCount + 1,
+                fetchFailureReason: s.error,
+            });
+        }
+    }
+}
+export { EmberError };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@freecorps/ember-react-query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "TanStack Query integration for Ember: emberQuery() and live query updates.",
+  "keywords": [
+    "ember",
+    "convex",
+    "cloudflare",
+    "workers",
+    "react",
+    "react-query",
+    "tanstack-query"
+  ],
+  "homepage": "https://github.com/freecorps/ember/tree/main/packages/react-query#readme",
+  "bugs": {
+    "url": "https://github.com/freecorps/ember/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freecorps/ember.git",
+    "directory": "packages/react-query"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@freecorps/ember-client": "0.2.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.80",
+    "react": ">=18"
+  }
+}