@lunora/vue 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ShallowRef, ComputedRef } from 'vue';
-import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions } from '@lunora/client';
-export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe, User } from '@lunora/client';
+import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ComputedRef, ShallowRef } from 'vue';
+import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
+export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, MutatorHandle, MutatorTransaction, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe, User } from '@lunora/client';
 import { PaginationStatus } from '@lunora/client/pagination';
 export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
@@ -101,6 +101,42 @@ declare const useAuth: () => UseAuthResult;
 * Call inside `setup()` / an active effect scope.
 */
 declare const useConnectionStatus: () => Readonly<Ref<ConnectionStatus>>;
+/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
+type FlagContext = Record<string, unknown>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
+/**
+* Subscribe to a single feature flag, live over Lunora's WebSocket.
+*
+* The returned `ref` holds `defaultValue` until the first evaluation lands, then
+* the server's resolved value — re-pushed whenever the provider re-evaluates
+* (e.g. a flag is toggled in Cloudflare Flagship). The flag's kind is inferred
+* from `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean
+* and `useFlag("hero", "control")` a string.
+*
+* `key` and `context` may be plain values, `ref`s, or getters: passing a reactive
+* source makes the subscription reactive — when it changes the old subscription
+* is torn down and a fresh one opens. `context` supplies a per-call targeting
+* context merged on top of the app's default `identify` targeting key.
+*
+* Evaluation runs through whatever OpenFeature provider the app wired in
+* `lunora/flags.ts`; the read never throws — a provider error resolves the
+* default (the same fail-open contract as server-side `ctx.flags`). Call inside
+* `setup()` (or any active effect scope); the subscription tears down on unmount.
+*/
+declare const useFlag: <T extends FlagValue>(key: MaybeRefOrGetter<string>, defaultValue: T, context?: MaybeRefOrGetter<FlagContext | undefined>) => Readonly<Ref<T>>;
+/**
+* Subscribe to several feature flags at once, live over Lunora's WebSocket.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the returned `ref` holds the same-shaped record with resolved
+* values (the defaults until each evaluation lands). A single `context` applies
+* to every flag and may be reactive. This is the batched form of {@link useFlag}
+* — one watcher manages one subscription per key.
+*/
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeRefOrGetter<FlagContext | undefined>) => Readonly<Ref<T>>;
 /**
 * The reactive handle returned by {@link useMutation} — the Vue counterpart to
 * React's `useMutation`, re-expressed with refs. The surface is identical across
@@ -136,6 +172,39 @@ interface MutationHandle<F extends FunctionReference> {
 * adapter-specific.
 */
 declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
+/**
+* The reactive handle returned by {@link useMutator} — the Vue counterpart to
+* `@lunora/react`'s `useMutator`, re-expressed with refs. The surface is
+* identical across the Lunora adapters (`@lunora/solid`, `/svelte`):
+* `error`/`isError`/`pending` are refs you read in a template and `mutate` is an
+* awaitable that resolves once the write is persisted (or rejects).
+*/
+interface MutatorHook<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Ref<Error | undefined>;
+  /** `true` when the latest invocation rejected. */
+  isError: ComputedRef<boolean>;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Ref<boolean>;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+* custom-mutator handle from `@lunora/db`'s `bindMutators` — the Vue equivalent
+* of `@lunora/react`'s `useMutator`. The optimistic overlay and
+* server-authoritative push are owned by the bound handle (and TanStack DB's
+* optimistic-transaction layer rebases pending overlays on every sync tick);
+* this composable only surfaces reactive state for the in-flight/error
+* lifecycle. Reads stay on the existing TanStack `useLiveQuery`; no new query
+* composable is needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS handle, so it
+* clears only once every concurrent call has settled.
+*/
+declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
 /** The element type of the `page` array a paginated query returns. */
@@ -345,4 +414,4 @@ interface UseSubscriptionResult<T> {
 * high-frequency streams.
 */
 declare const useSubscription: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<ArgsOf<F> | "skip">, options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
-export { AuthLoading, Authenticated, type HeartbeatReference, LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSubscriptionResult, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAuth, useConnectionStatus, useInfiniteQuery, useLunora, useMutation, usePaginatedQuery, usePresence, useQuery, useRateLimit, useSubscription };
+export { AuthLoading, Authenticated, type FlagContext, type FlagValue, type HeartbeatReference, LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSubscriptionResult, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAuth, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePresence, useQuery, useRateLimit, useSubscription };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ShallowRef, ComputedRef } from 'vue';
-import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions } from '@lunora/client';
-export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe, User } from '@lunora/client';
+import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ComputedRef, ShallowRef } from 'vue';
+import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
+export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, MutatorHandle, MutatorTransaction, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe, User } from '@lunora/client';
 import { PaginationStatus } from '@lunora/client/pagination';
 export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
@@ -101,6 +101,42 @@ declare const useAuth: () => UseAuthResult;
 * Call inside `setup()` / an active effect scope.
 */
 declare const useConnectionStatus: () => Readonly<Ref<ConnectionStatus>>;
+/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
+type FlagContext = Record<string, unknown>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
+/**
+* Subscribe to a single feature flag, live over Lunora's WebSocket.
+*
+* The returned `ref` holds `defaultValue` until the first evaluation lands, then
+* the server's resolved value — re-pushed whenever the provider re-evaluates
+* (e.g. a flag is toggled in Cloudflare Flagship). The flag's kind is inferred
+* from `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean
+* and `useFlag("hero", "control")` a string.
+*
+* `key` and `context` may be plain values, `ref`s, or getters: passing a reactive
+* source makes the subscription reactive — when it changes the old subscription
+* is torn down and a fresh one opens. `context` supplies a per-call targeting
+* context merged on top of the app's default `identify` targeting key.
+*
+* Evaluation runs through whatever OpenFeature provider the app wired in
+* `lunora/flags.ts`; the read never throws — a provider error resolves the
+* default (the same fail-open contract as server-side `ctx.flags`). Call inside
+* `setup()` (or any active effect scope); the subscription tears down on unmount.
+*/
+declare const useFlag: <T extends FlagValue>(key: MaybeRefOrGetter<string>, defaultValue: T, context?: MaybeRefOrGetter<FlagContext | undefined>) => Readonly<Ref<T>>;
+/**
+* Subscribe to several feature flags at once, live over Lunora's WebSocket.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the returned `ref` holds the same-shaped record with resolved
+* values (the defaults until each evaluation lands). A single `context` applies
+* to every flag and may be reactive. This is the batched form of {@link useFlag}
+* — one watcher manages one subscription per key.
+*/
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeRefOrGetter<FlagContext | undefined>) => Readonly<Ref<T>>;
 /**
 * The reactive handle returned by {@link useMutation} — the Vue counterpart to
 * React's `useMutation`, re-expressed with refs. The surface is identical across
@@ -136,6 +172,39 @@ interface MutationHandle<F extends FunctionReference> {
 * adapter-specific.
 */
 declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
+/**
+* The reactive handle returned by {@link useMutator} — the Vue counterpart to
+* `@lunora/react`'s `useMutator`, re-expressed with refs. The surface is
+* identical across the Lunora adapters (`@lunora/solid`, `/svelte`):
+* `error`/`isError`/`pending` are refs you read in a template and `mutate` is an
+* awaitable that resolves once the write is persisted (or rejects).
+*/
+interface MutatorHook<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Ref<Error | undefined>;
+  /** `true` when the latest invocation rejected. */
+  isError: ComputedRef<boolean>;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Ref<boolean>;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+* custom-mutator handle from `@lunora/db`'s `bindMutators` — the Vue equivalent
+* of `@lunora/react`'s `useMutator`. The optimistic overlay and
+* server-authoritative push are owned by the bound handle (and TanStack DB's
+* optimistic-transaction layer rebases pending overlays on every sync tick);
+* this composable only surfaces reactive state for the in-flight/error
+* lifecycle. Reads stay on the existing TanStack `useLiveQuery`; no new query
+* composable is needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS handle, so it
+* clears only once every concurrent call has settled.
+*/
+declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
 /** The element type of the `page` array a paginated query returns. */
@@ -345,4 +414,4 @@ interface UseSubscriptionResult<T> {
 * high-frequency streams.
 */
 declare const useSubscription: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<ArgsOf<F> | "skip">, options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
-export { AuthLoading, Authenticated, type HeartbeatReference, LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSubscriptionResult, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAuth, useConnectionStatus, useInfiniteQuery, useLunora, useMutation, usePaginatedQuery, usePresence, useQuery, useRateLimit, useSubscription };
+export { AuthLoading, Authenticated, type FlagContext, type FlagValue, type HeartbeatReference, LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSubscriptionResult, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAuth, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePresence, useQuery, useRateLimit, useSubscription };

package/dist/index.mjs

@@ -1,9 +1,11 @@
-export { AuthLoading, Authenticated, Unauthenticated } from './packem_shared/Authenticated-_6-uOycE.mjs';
+export { AuthLoading, Authenticated, Unauthenticated } from './packem_shared/AuthLoading-_6-uOycE.mjs';
 export { hydratePreloaded } from './packem_shared/hydratePreloaded-rVY68iFv.mjs';
 export { LUNORA_INJECTION_KEY, createLunora, provideLunora, useLunora } from './packem_shared/LUNORA_INJECTION_KEY-DtFXLDQ_.mjs';
 export { useAuth } from './packem_shared/useAuth-C2aEzXXH.mjs';
 export { default as useConnectionStatus } from './packem_shared/useConnectionStatus-CDgduQYe.mjs';
+export { useFlag, useFlags } from './packem_shared/useFlag-DRtODeBp.mjs';
 export { useMutation } from './packem_shared/useMutation-DWubV5pv.mjs';
+export { useMutator } from './packem_shared/useMutator-B_Ahs_ZN.mjs';
 export { useInfiniteQuery, usePaginatedQuery } from './packem_shared/useInfiniteQuery-CEfbw7Nw.mjs';
 export { usePresence } from './packem_shared/usePresence-BeN5xaZM.mjs';
 export { subscribeToQuery, useQuery } from './packem_shared/subscribeToQuery-Cv5YL-SI.mjs';

package/dist/packem_shared/useFlag-DRtODeBp.mjs

@@ -0,0 +1,108 @@
+import { shallowRef, watch, toValue } from 'vue';
+import { useLunora } from './LUNORA_INJECTION_KEY-DtFXLDQ_.mjs';
+
+const compareKeys = (a, b) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const stableStringify = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  if (typeof value === "bigint") {
+    throw new TypeError("stableStringify: cannot use a bigint in a cache key (query/subscription/shape args) — pass it as a string");
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) {
+    const name = value.constructor?.name ?? "value";
+    throw new TypeError(
+      `stableStringify: cannot use a ${name} in a cache key (query/subscription/shape args) — only plain objects, arrays, and JSON primitives are supported`
+    );
+  }
+  const record = value;
+  const keys = Object.keys(record).toSorted(compareKeys);
+  const parts = [];
+  for (const key of keys) {
+    const raw = record[key];
+    if (raw === void 0) {
+      continue;
+    }
+    parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
+  }
+  return `{${parts.join(",")}}`;
+};
+
+const FLAGS_EVAL_PATH = "__lunora_flags__:eval";
+const flagKind = (value) => {
+  const kind = typeof value;
+  if (kind === "boolean" || kind === "number" || kind === "string") {
+    return kind;
+  }
+  return "object";
+};
+const flagsReference = { __lunoraRef: FLAGS_EVAL_PATH };
+const serializeContext = (context) => context === void 0 ? "" : stableStringify(context);
+const useFlag = (key, defaultValue, context) => {
+  const client = useLunora();
+  const type = flagKind(defaultValue);
+  const value = shallowRef(defaultValue);
+  watch(
+    () => `${toValue(key)}\0${serializeContext(toValue(context))}`,
+    (_serialized, _previous, onCleanup) => {
+      const currentKey = toValue(key);
+      const currentContext = toValue(context);
+      value.value = defaultValue;
+      let unsubscribe;
+      try {
+        unsubscribe = client.subscribe(flagsReference, { context: currentContext, default: defaultValue, key: currentKey, type }, (next) => {
+          value.value = next;
+        });
+      } catch {
+        return;
+      }
+      onCleanup(unsubscribe);
+    },
+    { immediate: true }
+  );
+  return value;
+};
+const useFlags = (flags, context) => {
+  const client = useLunora();
+  const values = shallowRef(flags);
+  const spec = stableStringify(flags);
+  watch(
+    () => `${spec}\0${serializeContext(toValue(context))}`,
+    (_serialized, _previous, onCleanup) => {
+      const currentContext = toValue(context);
+      values.value = flags;
+      const unsubscribes = [];
+      for (const [key, defaultValue] of Object.entries(flags)) {
+        try {
+          unsubscribes.push(
+            client.subscribe(flagsReference, { context: currentContext, default: defaultValue, key, type: flagKind(defaultValue) }, (next) => {
+              values.value = { ...values.value, [key]: next };
+            })
+          );
+        } catch {
+        }
+      }
+      onCleanup(() => {
+        for (const unsubscribe of unsubscribes) {
+          unsubscribe();
+        }
+      });
+    },
+    { immediate: true }
+  );
+  return values;
+};
+
+export { useFlag, useFlags };

package/dist/packem_shared/useMutator-B_Ahs_ZN.mjs

@@ -0,0 +1,19 @@
+import { createMutatorRunner } from '@lunora/client';
+import { shallowRef, computed } from 'vue';
+
+const useMutator = (handle) => {
+  const error = shallowRef(void 0);
+  const pending = shallowRef(false);
+  const isError = computed(() => error.value !== void 0);
+  const { mutate, reset } = createMutatorRunner(handle, {
+    setError: (value) => {
+      error.value = value;
+    },
+    setPending: (value) => {
+      pending.value = value;
+    }
+  });
+  return { error, isError, mutate, pending, reset };
+};
+
+export { useMutator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/vue",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.21",
   "description": "Vue adapter for Lunora — live composables, optimistic mutations, and reactive loaders",
   "keywords": [
     "cloudflare",
@@ -25,7 +25,7 @@
     "directory": "packages/vue"
   },
   "files": [
-    "dist",
+    "./dist",
     "README.md",
     "LICENSE.md",
     "__assets__"
@@ -54,9 +54,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.1",
-    "@lunora/ratelimit": "1.0.0-alpha.2",
-    "@lunora/runtime": "1.0.0-alpha.1"
+    "@lunora/client": "1.0.0-alpha.13",
+    "@lunora/ratelimit": "1.0.0-alpha.3",
+    "@lunora/runtime": "1.0.0-alpha.12"
   },
   "peerDependencies": {
     "vue": "^3.5.0"