@rustra/react 0.5.0 → 0.7.1

package/README.md

@@ -19,5 +19,33 @@ function Item({ id }: { id: string }) {
 ```
 
 The package provides `RustraProvider`, `useRustraEngine`, `useCommand`,
-`useMutation`, and `useEvent`. React is a peer dependency; configure the
-platform-specific Rustra engine before rendering the provider.
+`useMutation`, `useEvent`, and `useSuspenseCommand`. React is a peer dependency;
+configure the platform-specific Rustra engine before rendering the provider.
+
+`useSuspenseCommand(commandFn, input?, options?)` is the Suspense-compatible read:
+it suspends by throwing the in-flight promise until the command resolves, then
+returns the value directly (a rejection is re-thrown to the nearest error
+boundary). Results live in a module-level cache keyed by command name + serialized
+input for the whole session — there is no eviction — so call
+`invalidateCommands(commandName?)` to drop one command's entries (or, with no
+argument, the whole cache) and make the next render re-invoke.
+
+```tsx
+import { Suspense } from 'react';
+import { invalidateCommands, useSuspenseCommand } from '@rustra/react';
+import { getItem, saveItem } from './generated/commands.js';
+
+function Item({ id }: { id: string }) {
+  const item = useSuspenseCommand(getItem, { id }); // suspends until resolved
+  return <span>{item.name}</span>;
+}
+
+async function rename(id: string, name: string) {
+  await saveItem({ id, name });
+  invalidateCommands('getItem'); // next render of <Item> re-fetches
+}
+
+<Suspense fallback={<span>Loading...</span>}>
+  <Item id="item-1" />
+</Suspense>;
+```

package/dist/index.d.ts

@@ -26,6 +26,8 @@ export { useCommand } from './useCommand.js';
 export type { UseCommandOptions, UseCommandResult, CommandFn, VoidCommandFn, } from './useCommand.js';
 export { useMutation } from './useMutation.js';
 export type { UseMutationOptions, UseMutationResult } from './useMutation.js';
+export { useSuspenseCommand, invalidateCommands } from './useSuspenseCommand.js';
+export type { SuspenseEntry } from './useSuspenseCommand.js';
 export { useEvent } from './useEvent.js';
 export type { EventCallback, UnsubscribeFn, SubscribeResult, SubscribeFn } from './useEvent.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACjF,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -23,5 +23,6 @@
 export { RustraProvider, useRustraEngine } from './context.js';
 export { useCommand } from './useCommand.js';
 export { useMutation } from './useMutation.js';
+export { useSuspenseCommand, invalidateCommands } from './useSuspenseCommand.js';
 export { useEvent } from './useEvent.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQ7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQ7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGjF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/useSuspenseCommand.d.ts

@@ -0,0 +1,50 @@
+import type { InvokeOptions } from '@rustra/types';
+import type { CommandFn, VoidCommandFn } from './useCommand.js';
+/**
+ * Cache entry state machine — `pending` until the in-flight promise settles,
+ * then `fulfilled` (value stored) or `rejected` (error stored).
+ */
+export interface SuspenseEntry<O = unknown> {
+    /** Owning command — `invalidateCommands` matches this field, not the key prefix. */
+    commandName: string;
+    promise: Promise<O>;
+    status: 'pending' | 'fulfilled' | 'rejected';
+    value?: O;
+    error?: unknown;
+}
+/**
+ * Pure cache state machine: returns the existing entry for `key` when present,
+ * otherwise creates one by invoking `start()` and drives it to its terminal
+ * state. Settling updates the entry in place, so later accessors read the
+ * cached value/error without re-invoking. Rejections are normalized to `Error`
+ * (matching `useCommand`/`useMutation`); the stored object is re-thrown as-is.
+ *
+ * Exported for testing — the hook stays thin, and this is testable without
+ * React (a thrown promise is awkward to exercise under SSR renderToString).
+ */
+export declare function resolveSuspenseEntry<O>(key: string, commandName: string, start: () => Promise<O>): SuspenseEntry<O>;
+/**
+ * Invalidate cached suspense entries.
+ *
+ * - `invalidateCommands('getItem')` — drop only that command's entries,
+ *   matched by the entry's owning command (exact, so command names containing
+ *   `::` cannot be over-matched by a shorter prefix).
+ * - `invalidateCommands()` — drop every cached entry.
+ *
+ * Works outside components (module-level cache), e.g. after a mutation.
+ */
+export declare function invalidateCommands(commandName?: string): void;
+/**
+ * Suspense-compatible command hook. Must be called under a Suspense boundary.
+ *
+ * First call starts the invocation and throws the in-flight promise —
+ * thrown-thenable Suspense on React 18, `use` on React 19. Once settled,
+ * subsequent calls return the cached value. A rejected invocation re-throws
+ * the same stored error object on every access (error boundary contract) until
+ * `invalidateCommands` clears it.
+ *
+ * `options` are honored only on the first invocation per key; later calls
+ * reuse the cached promise.
+ */
+export declare function useSuspenseCommand<I, O>(commandFn: CommandFn<I, O> | VoidCommandFn<O>, input?: I, options?: InvokeOptions): O;
+//# sourceMappingURL=useSuspenseCommand.d.ts.map

package/dist/useSuspenseCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSuspenseCommand.d.ts","sourceRoot":"","sources":["../src/useSuspenseCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhE;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACtB,aAAa,CAAC,CAAC,CAAC,CAmBlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,EAC7C,KAAK,CAAC,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,aAAa,GACtB,CAAC,CAYH"}

package/dist/useSuspenseCommand.js

@@ -0,0 +1,85 @@
+import { resolveCommandId } from '@rustra/types';
+import { useRustraEngine } from './context.js';
+import { inputKey } from './input-key.js';
+/**
+ * Module-level suspense cache. Key is the resolved command name followed by
+ * `::` and the serialized input — an absent input collapses to the bare
+ * `commandName + '::'` suffix, otherwise `inputKey(input)` (bigint-safe).
+ *
+ * No eviction policy by design (YAGNI) — entries live for the session.
+ */
+const cache = new Map();
+function cacheKey(commandName, input) {
+    return `${commandName}::${input === undefined ? '' : inputKey(input)}`;
+}
+/**
+ * Pure cache state machine: returns the existing entry for `key` when present,
+ * otherwise creates one by invoking `start()` and drives it to its terminal
+ * state. Settling updates the entry in place, so later accessors read the
+ * cached value/error without re-invoking. Rejections are normalized to `Error`
+ * (matching `useCommand`/`useMutation`); the stored object is re-thrown as-is.
+ *
+ * Exported for testing — the hook stays thin, and this is testable without
+ * React (a thrown promise is awkward to exercise under SSR renderToString).
+ */
+export function resolveSuspenseEntry(key, commandName, start) {
+    const existing = cache.get(key);
+    if (existing)
+        return existing;
+    const promise = start();
+    const entry = { commandName, promise, status: 'pending' };
+    cache.set(key, entry);
+    promise.then((value) => {
+        entry.status = 'fulfilled';
+        entry.value = value;
+    }, (err) => {
+        entry.status = 'rejected';
+        entry.error = err instanceof Error ? err : new Error(String(err));
+    });
+    return entry;
+}
+/**
+ * Invalidate cached suspense entries.
+ *
+ * - `invalidateCommands('getItem')` — drop only that command's entries,
+ *   matched by the entry's owning command (exact, so command names containing
+ *   `::` cannot be over-matched by a shorter prefix).
+ * - `invalidateCommands()` — drop every cached entry.
+ *
+ * Works outside components (module-level cache), e.g. after a mutation.
+ */
+export function invalidateCommands(commandName) {
+    if (commandName === undefined) {
+        cache.clear();
+        return;
+    }
+    for (const [key, entry] of cache) {
+        if (entry.commandName === commandName)
+            cache.delete(key);
+    }
+}
+/**
+ * Suspense-compatible command hook. Must be called under a Suspense boundary.
+ *
+ * First call starts the invocation and throws the in-flight promise —
+ * thrown-thenable Suspense on React 18, `use` on React 19. Once settled,
+ * subsequent calls return the cached value. A rejected invocation re-throws
+ * the same stored error object on every access (error boundary contract) until
+ * `invalidateCommands` clears it.
+ *
+ * `options` are honored only on the first invocation per key; later calls
+ * reuse the cached promise.
+ */
+export function useSuspenseCommand(commandFn, input, options) {
+    const engine = useRustraEngine();
+    // minify-안전 식별: 코드젠이 심은 commandId 를 우선한다 (Function.name 은
+    // 프로덕션 번들러 mangling 으로 바뀔 수 있다).
+    const commandName = resolveCommandId(commandFn);
+    const entry = resolveSuspenseEntry(cacheKey(commandName, input), commandName, () => engine.invoke(commandName, input, options));
+    if (entry.status === 'pending')
+        throw entry.promise;
+    if (entry.status === 'rejected')
+        throw entry.error;
+    return entry.value;
+}
+//# sourceMappingURL=useSuspenseCommand.js.map

package/dist/useSuspenseCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSuspenseCommand.js","sourceRoot":"","sources":["../src/useSuspenseCommand.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAe1C;;;;;;GAMG;AACH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;AAE/C,SAAS,QAAQ,CAAC,WAAmB,EAAE,KAAc;IACnD,OAAO,GAAG,WAAW,KAAK,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACzE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,WAAmB,EACnB,KAAuB;IAEvB,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,QAAQ;QAAE,OAAO,QAA4B,CAAC;IAElD,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC;IACxB,MAAM,KAAK,GAAqB,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC5E,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAEtB,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;QACR,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;QAC3B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;IACtB,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;QACf,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC;QAC1B,KAAK,CAAC,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpE,CAAC,CACF,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAoB;IACrD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,WAAW,KAAK,WAAW;YAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA6C,EAC7C,KAAS,EACT,OAAuB;IAEvB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,iCAAiC;IACjC,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,oBAAoB,CAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CACpF,MAAM,CAAC,MAAM,CAAI,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,CAC9C,CAAC;IAEF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,KAAK,CAAC,OAAO,CAAC;IACpD,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU;QAAE,MAAM,KAAK,CAAC,KAAK,CAAC;IACnD,OAAO,KAAK,CAAC,KAAU,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rustra/react",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "description": "React and React Native bindings and hooks for rustra-bridge",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "react": ">=18.0.0"
   },
   "dependencies": {
-    "@rustra/types": "^0.6.0"
+    "@rustra/types": "^0.9.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",