@freecorps/ember-react 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
 
-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.
+React bindings for Ember: EmberProvider, useQuery, useMutation, useAction, usePaginatedQuery.
+
+Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
+Objects. Source: [`packages/react`](https://github.com/freecorps/ember/tree/main/packages/react).
+
+```sh
+npm install @freecorps/ember-react
+```
+
+License: MIT.

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { type ReactNode } from "react";
+import { type ConnectionState, type EmberClient, type FunctionReference, type OptimisticUpdate, type QuerySnapshot, type ShardOptions } from "@freecorps/ember-client";
+export interface EmberProviderProps {
+    client: EmberClient;
+    children?: ReactNode;
+}
+export declare function EmberProvider({ client, children }: EmberProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<EmberClient | null>>;
+export declare function useEmberClient(): EmberClient;
+type QueryRef = FunctionReference<"query"> | string;
+type ArgsOf<Q> = Q extends FunctionReference<any, infer A, any> ? A : Record<string, unknown>;
+type ReturnOf<Q> = Q extends FunctionReference<any, any, infer R> ? R : unknown;
+/**
+ * The full snapshot of a live query (`status`, `value`, `error`, `optimistic`, and `source` — `"local"` or `"cache"`
+ * while the value comes from offline storage, before the server answers). Args are compared by value, so an
+ * inline object is fine. `"skip"` subscribes to nothing.
+ *
+ * Offline-first: give the client a `StorageAdapter` (`new EmberClient({ url, storage: indexedDbStorage({ name,
+ * schema, queries }) })`, from `@freecorps/ember-offline/indexeddb`); `useQuery` then renders stored / locally
+ * computed results on a cold start without network.
+ */
+export declare function useQuerySnapshot<Q extends QueryRef>(ref: Q, args: ArgsOf<Q> | "skip", opts?: ShardOptions): QuerySnapshot<ReturnOf<Q>>;
+/**
+ * Live query value: `undefined` while loading (or skipped). Errors are thrown to the nearest error boundary,
+ * like `convex/react`. Use `useQuerySnapshot` to handle them inline.
+ */
+export declare function useQuery<Q extends QueryRef>(ref: Q, args?: ArgsOf<Q> | "skip", opts?: ShardOptions): ReturnOf<Q> | undefined;
+type MutationRef = FunctionReference<"mutation"> | string;
+export interface ReactMutation<M extends MutationRef> {
+    (args?: ArgsOf<M>): Promise<ReturnOf<M>>;
+    /** A new mutation function that applies `update` optimistically on every call. */
+    withOptimisticUpdate(update: OptimisticUpdate<ArgsOf<M>>): ReactMutation<M>;
+}
+/** A stable function that runs the mutation. `.withOptimisticUpdate(fn)` adds an optimistic update. */
+export declare function useMutation<M extends MutationRef>(ref: M, opts?: ShardOptions): ReactMutation<M>;
+type ActionRef = FunctionReference<"action"> | string;
+/** Calls the action over HTTP (`POST /api/action`); the shard defaults to the client's default shard. */
+export declare function useAction<A extends ActionRef>(ref: A, opts?: ShardOptions): (args?: ArgsOf<A>) => Promise<ReturnOf<A>>;
+/** Online flag, per-shard socket state and the number of unconfirmed mutations. */
+export declare function useConnectionState(): ConnectionState;
+/** What a paginated query receives in `args.paginationOpts`. */
+export interface PaginationOptions {
+    numItems: number;
+    cursor: string | null;
+}
+/** What a paginated query must return. */
+export interface PaginationResult<T> {
+    page: T[];
+    isDone: boolean;
+    continueCursor: string | null;
+}
+export type PaginationStatus = "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted";
+export interface UsePaginatedQueryResult<T> {
+    results: T[];
+    status: PaginationStatus;
+    isLoading: boolean;
+    loadMore(numItems: number): void;
+}
+type PageItem<Q> = ReturnOf<Q> extends PaginationResult<infer T> ? T : unknown;
+type PaginatedArgs<Q> = Omit<ArgsOf<Q>, "paginationOpts">;
+/**
+ * Basic cursor pagination: page `i` is its own live query with `paginationOpts: {numItems, cursor}`, where the
+ * cursor is page `i-1`'s `continueCursor`. Pages are concatenated. Page boundaries do not split/merge yet (Phase 4).
+ */
+export declare function usePaginatedQuery<Q extends QueryRef>(ref: Q, args: PaginatedArgs<Q> | "skip", opts: ShardOptions & {
+    initialNumItems: number;
+}): UsePaginatedQueryResult<PageItem<Q>>;
+export type { QuerySnapshot, ConnectionState } from "@freecorps/ember-client";

package/dist/index.js

@@ -0,0 +1,174 @@
+// React bindings for @freecorps/ember-client. No DOM APIs: works in React DOM and React Native.
+import { createContext, createElement, useCallback, useContext, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { getFunctionName, stableStringify, } from "@freecorps/ember-client";
+const EmberContext = createContext(null);
+export function EmberProvider({ client, children }) {
+    return createElement(EmberContext.Provider, { value: client }, children);
+}
+export function useEmberClient() {
+    const c = useContext(EmberContext);
+    if (!c)
+        throw new Error("Ember hooks need an <EmberProvider client={...}> above them");
+    return c;
+}
+const LOADING = Object.freeze({ status: "loading", value: undefined, error: undefined, optimistic: false });
+const noopSubscribe = () => () => { };
+const getLoading = () => LOADING;
+/**
+ * The full snapshot of a live query (`status`, `value`, `error`, `optimistic`, and `source` — `"local"` or `"cache"`
+ * while the value comes from offline storage, before the server answers). Args are compared by value, so an
+ * inline object is fine. `"skip"` subscribes to nothing.
+ *
+ * Offline-first: give the client a `StorageAdapter` (`new EmberClient({ url, storage: indexedDbStorage({ name,
+ * schema, queries }) })`, from `@freecorps/ember-offline/indexeddb`); `useQuery` then renders stored / locally
+ * computed results on a cold start without network.
+ */
+export function useQuerySnapshot(ref, args, opts) {
+    const client = useEmberClient();
+    const name = getFunctionName(ref);
+    const skip = args === "skip";
+    const argsKey = skip ? null : stableStringify(args ?? {});
+    const shard = opts?.shard;
+    const handle = useMemo(() => (skip ? null : client.watchQuery(name, args, shard === undefined ? undefined : { shard })), 
+    // args are read through argsKey
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, name, argsKey, shard]);
+    return useSyncExternalStore(handle?.subscribe ?? noopSubscribe, handle?.getSnapshot ?? getLoading, handle?.getSnapshot ?? getLoading);
+}
+/**
+ * Live query value: `undefined` while loading (or skipped). Errors are thrown to the nearest error boundary,
+ * like `convex/react`. Use `useQuerySnapshot` to handle them inline.
+ */
+export function useQuery(ref, args = {}, opts) {
+    const s = useQuerySnapshot(ref, args, opts);
+    if (s.status === "error")
+        throw s.error;
+    return s.value;
+}
+function makeMutation(client, name, opts, update) {
+    const f = ((args) => {
+        const o = {};
+        if (opts?.shard !== undefined)
+            o.shard = opts.shard;
+        if (update)
+            o.optimisticUpdate = update;
+        return client.mutation(name, args, o);
+    });
+    f.withOptimisticUpdate = (u) => makeMutation(client, name, opts, u);
+    return f;
+}
+/** A stable function that runs the mutation. `.withOptimisticUpdate(fn)` adds an optimistic update. */
+export function useMutation(ref, opts) {
+    const client = useEmberClient();
+    const name = getFunctionName(ref);
+    const shard = opts?.shard;
+    return useMemo(() => makeMutation(client, name, shard === undefined ? undefined : { shard }), [client, name, shard]);
+}
+/** Calls the action over HTTP (`POST /api/action`); the shard defaults to the client's default shard. */
+export function useAction(ref, opts) {
+    const client = useEmberClient();
+    const name = getFunctionName(ref);
+    const shard = opts?.shard;
+    return useCallback((args) => client.action(name, args, shard === undefined ? undefined : { shard }), [client, name, shard]);
+}
+/** Online flag, per-shard socket state and the number of unconfirmed mutations. */
+export function useConnectionState() {
+    const client = useEmberClient();
+    const subscribe = useCallback((l) => client.onConnectionStateChange(l), [client]);
+    const get = useCallback(() => client.connectionState(), [client]);
+    return useSyncExternalStore(subscribe, get, get);
+}
+/**
+ * Basic cursor pagination: page `i` is its own live query with `paginationOpts: {numItems, cursor}`, where the
+ * cursor is page `i-1`'s `continueCursor`. Pages are concatenated. Page boundaries do not split/merge yet (Phase 4).
+ */
+export function usePaginatedQuery(ref, args, opts) {
+    const client = useEmberClient();
+    const name = getFunctionName(ref);
+    const skip = args === "skip";
+    const argsKey = skip ? null : stableStringify(args ?? {});
+    const shard = opts.shard;
+    const [state, setState] = useState({ key: argsKey, sizes: [opts.initialNumItems] });
+    const sizes = state.key === argsKey ? state.sizes : [opts.initialNumItems];
+    if (state.key !== argsKey)
+        setState({ key: argsKey, sizes });
+    // Each page's cursor depends on the previous page's result, so handles are derived from the snapshots.
+    const cache = useRef(null);
+    const sizesKey = sizes.join(",");
+    const handles = useCallback(() => {
+        if (skip)
+            return [];
+        const out = [];
+        let cursor = null;
+        for (const numItems of sizes) {
+            const h = client.watchQuery(name, { ...args, paginationOpts: { numItems, cursor } }, shard === undefined ? undefined : { shard });
+            out.push(h);
+            const s = h.getSnapshot();
+            const v = s.value;
+            if (!v || v.isDone || v.continueCursor === null)
+                break;
+            cursor = v.continueCursor;
+        }
+        return out;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, name, argsKey, shard, sizesKey, skip]);
+    const subscribe = useCallback((listener) => {
+        // Re-derive the handle list whenever a page changes (a new continueCursor adds the next page).
+        let offs = [];
+        const resubscribe = () => {
+            const next = handles().map((h) => h.subscribe(onChange));
+            for (const off of offs)
+                off();
+            offs = next;
+        };
+        const onChange = () => {
+            resubscribe();
+            listener();
+        };
+        resubscribe();
+        return () => {
+            for (const off of offs)
+                off();
+            offs = [];
+        };
+    }, [handles]);
+    const getSnapshot = useCallback(() => {
+        const snaps = handles().map((h) => h.getSnapshot());
+        const prev = cache.current;
+        if (prev && prev.snaps.length === snaps.length && prev.snaps.every((s, i) => s === snaps[i]))
+            return prev.result;
+        const results = [];
+        let status = skip ? "LoadingFirstPage" : "CanLoadMore";
+        let error;
+        for (let i = 0; i < snaps.length; i++) {
+            const s = snaps[i];
+            if (s.status === "error") {
+                error = s.error;
+                break;
+            }
+            const v = s.value;
+            if (!v) {
+                status = i === 0 ? "LoadingFirstPage" : "LoadingMore";
+                break;
+            }
+            results.push(...v.page);
+            if (v.isDone)
+                status = "Exhausted";
+        }
+        if (status === "CanLoadMore" && snaps.length < sizes.length)
+            status = "LoadingMore";
+        const loadMore = (n) => {
+            if (status !== "CanLoadMore")
+                return;
+            setState((st) => ({ key: st.key, sizes: [...st.sizes, n] }));
+        };
+        const result = { results, status, isLoading: status === "LoadingFirstPage" || status === "LoadingMore", loadMore, error };
+        cache.current = { snaps, result };
+        return result;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handles, skip, sizesKey]);
+    const { error, ...result } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    if (error)
+        throw error;
+    return result;
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@freecorps/ember-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "React bindings for Ember: EmberProvider, useQuery, useMutation, useAction, usePaginatedQuery.",
+  "keywords": [
+    "ember",
+    "convex",
+    "cloudflare",
+    "workers",
+    "react",
+    "hooks",
+    "realtime"
+  ],
+  "homepage": "https://github.com/freecorps/ember/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/freecorps/ember/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freecorps/ember.git",
+    "directory": "packages/react"
+  },
+  "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": {
+    "react": ">=18"
+  }
+}