@lunora/solid 1.0.0-alpha.5 → 1.0.0-alpha.7

package/README.md

@@ -103,6 +103,8 @@ render(
 | `createAuth`                                        | `useAuth`             | Reactive auth state (`token`, `user` signals + `setToken`).                      |
 | `Authenticated` / `AuthLoading` / `Unauthenticated` | —                     | Auth-gate components rendering `children` per identity state.                    |
 | `createPresence`                                    | `usePresence`         | Collaborative-awareness — heartbeat + live present-members signal.               |
+| `createFlag`                                        | `useFlag`             | Live OpenFeature flag accessor — returns `default` until the server answers.     |
+| `createFlags`                                       | `useFlags`            | Batch variant — an accessor of one value per key in the defaults map.            |
 | `createRateLimit`                                   | `useRateLimit`        | Client-side rate-limit mirror — `ok`, `disabled`, `retryAfter` as signals.       |
 | `createConnectionStatus`                            | `useConnectionStatus` | Reactive connection state signal.                                                |
 | `hydratePreloaded`                                  | `usePreloadedQuery`   | Seed a query synchronously from an SSR `Preloaded` token, then go live.          |

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { LunoraClient, User, ConnectionStatus, FunctionReference, ArgsOf, MutationCallOptions, ReturnOf, Preloaded } from '@lunora/client';
-export type { ArgsOf, FunctionReference, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
+import { LunoraClient, User, ConnectionStatus, FunctionReference, ArgsOf, MutationCallOptions, ReturnOf, MutatorHandle, Preloaded } from '@lunora/client';
+export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
 import { Context, JSX, Accessor } from 'solid-js';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
@@ -62,6 +62,43 @@ declare const Unauthenticated: (props: AuthGateProps) => JSX.Element;
 * scope disposes (component unmount). Call inside a component / reactive root.
 */
 declare const createConnectionStatus: () => Accessor<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;
+/** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
+type MaybeAccessor<T> = Accessor<T> | T;
+/**
+* Subscribe to a single feature flag and return a reactive accessor of its value.
+*
+* The accessor reads `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 `createFlag("dark", false)` reads a boolean
+* and `createFlag("hero", "control")` a string.
+*
+* `key` and `context` may be plain values or accessors; passing an accessor makes
+* the subscription reactive — when it changes the old subscription is torn down
+* (via `onCleanup`) 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`).
+*/
+declare const createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+/**
+* Subscribe to several feature flags at once and return a reactive accessor of
+* the resolved record.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the accessor reads the same-shaped record with resolved values
+* (the defaults until each evaluation lands). A single `context` applies to every
+* flag and may be an accessor. This is the batched form of {@link createFlag}.
+*/
+declare const createFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
 interface MutationHandle<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
   data: Accessor<ReturnOf<F> | undefined>;
@@ -107,6 +144,38 @@ declare const createMutationForClient: <F extends FunctionReference>(client: Mut
 * down, so `mutate` stays durable across reconnects.
 */
 declare const createMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
+/**
+* The reactive handle returned by {@link createMutator} — the Solid counterpart
+* to `@lunora/react`'s `useMutator`, re-expressed with signals.
+* `error`/`isError`/`pending` are accessors 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: Accessor<Error | undefined>;
+  /** `true` when the latest invocation rejected. */
+  isError: Accessor<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: Accessor<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 Solid
+* 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 primitive only surfaces signal state for the in-flight/error lifecycle.
+* Reads stay on the existing TanStack `useLiveQuery`; no new query primitive is
+* needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS handle, so it
+* clears only once every concurrent call has settled.
+*/
+declare const createMutator: <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. */
@@ -336,4 +405,4 @@ interface LunoraProviderProps {
 * ```
 */
 declare const LunoraProvider: (props: LunoraProviderProps) => JSX.Element;
-export { AuthLoading, Authenticated, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateSubscriptionResult, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createInfiniteQuery, createMutation, createMutationForClient, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };
+export { AuthLoading, Authenticated, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateSubscriptionResult, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { LunoraClient, User, ConnectionStatus, FunctionReference, ArgsOf, MutationCallOptions, ReturnOf, Preloaded } from '@lunora/client';
-export type { ArgsOf, FunctionReference, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
+import { LunoraClient, User, ConnectionStatus, FunctionReference, ArgsOf, MutationCallOptions, ReturnOf, MutatorHandle, Preloaded } from '@lunora/client';
+export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
 import { Context, JSX, Accessor } from 'solid-js';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
@@ -62,6 +62,43 @@ declare const Unauthenticated: (props: AuthGateProps) => JSX.Element;
 * scope disposes (component unmount). Call inside a component / reactive root.
 */
 declare const createConnectionStatus: () => Accessor<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;
+/** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
+type MaybeAccessor<T> = Accessor<T> | T;
+/**
+* Subscribe to a single feature flag and return a reactive accessor of its value.
+*
+* The accessor reads `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 `createFlag("dark", false)` reads a boolean
+* and `createFlag("hero", "control")` a string.
+*
+* `key` and `context` may be plain values or accessors; passing an accessor makes
+* the subscription reactive — when it changes the old subscription is torn down
+* (via `onCleanup`) 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`).
+*/
+declare const createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+/**
+* Subscribe to several feature flags at once and return a reactive accessor of
+* the resolved record.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the accessor reads the same-shaped record with resolved values
+* (the defaults until each evaluation lands). A single `context` applies to every
+* flag and may be an accessor. This is the batched form of {@link createFlag}.
+*/
+declare const createFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
 interface MutationHandle<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
   data: Accessor<ReturnOf<F> | undefined>;
@@ -107,6 +144,38 @@ declare const createMutationForClient: <F extends FunctionReference>(client: Mut
 * down, so `mutate` stays durable across reconnects.
 */
 declare const createMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
+/**
+* The reactive handle returned by {@link createMutator} — the Solid counterpart
+* to `@lunora/react`'s `useMutator`, re-expressed with signals.
+* `error`/`isError`/`pending` are accessors 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: Accessor<Error | undefined>;
+  /** `true` when the latest invocation rejected. */
+  isError: Accessor<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: Accessor<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 Solid
+* 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 primitive only surfaces signal state for the in-flight/error lifecycle.
+* Reads stay on the existing TanStack `useLiveQuery`; no new query primitive is
+* needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS handle, so it
+* clears only once every concurrent call has settled.
+*/
+declare const createMutator: <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. */
@@ -336,4 +405,4 @@ interface LunoraProviderProps {
 * ```
 */
 declare const LunoraProvider: (props: LunoraProviderProps) => JSX.Element;
-export { AuthLoading, Authenticated, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateSubscriptionResult, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createInfiniteQuery, createMutation, createMutationForClient, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };
+export { AuthLoading, Authenticated, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateSubscriptionResult, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };

package/dist/index.mjs

@@ -1,7 +1,9 @@
 export { LunoraContext, useLunora } from './packem_shared/LunoraContext-C9SpKj54.mjs';
 export { AuthLoading, Authenticated, Unauthenticated, createAuth } from './packem_shared/AuthLoading-RMT5Q_eE.mjs';
 export { default as createConnectionStatus } from './packem_shared/createConnectionStatus-D8GPatZX.mjs';
+export { createFlag, createFlags } from './packem_shared/createFlag-BDunYuaH.mjs';
 export { createMutation, createMutationForClient } from './packem_shared/createMutation-C7BxzO0y.mjs';
+export { createMutator } from './packem_shared/createMutator-foSnPJPt.mjs';
 export { createInfiniteQuery, createPaginatedQuery } from './packem_shared/createInfiniteQuery-DyMvQ2Qy.mjs';
 export { createPresence } from './packem_shared/createPresence-DiAak1Jw.mjs';
 export { createQuery } from './packem_shared/createQuery-D8mdHfyQ.mjs';

package/dist/packem_shared/createFlag-BDunYuaH.mjs

@@ -0,0 +1,106 @@
+import { createSignal, createEffect, on, onCleanup } from 'solid-js';
+import { useLunora } from './LunoraContext-C9SpKj54.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 (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  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 resolveMaybe = (value) => typeof value === "function" ? value() : value;
+const serializeContext = (context) => context === void 0 ? "" : stableStringify(context);
+const createFlag = (key, defaultValue, context) => {
+  const client = useLunora();
+  const type = flagKind(defaultValue);
+  const [value, setValue] = createSignal(defaultValue);
+  createEffect(on(() => `${resolveMaybe(key)} ${serializeContext(resolveMaybe(context))}`, () => {
+    const currentKey = resolveMaybe(key);
+    const currentContext = resolveMaybe(context);
+    setValue(() => defaultValue);
+    let unsubscribe;
+    try {
+      unsubscribe = client.subscribe(flagsReference, {
+        context: currentContext,
+        default: defaultValue,
+        key: currentKey,
+        type
+      }, (next) => {
+        setValue(() => next);
+      });
+    } catch {
+      return;
+    }
+    onCleanup(unsubscribe);
+  }));
+  return value;
+};
+const createFlags = (flags, context) => {
+  const client = useLunora();
+  const [values, setValues] = createSignal(flags);
+  const spec = stableStringify(flags);
+  createEffect(on(() => `${spec} ${serializeContext(resolveMaybe(context))}`, () => {
+    const currentContext = resolveMaybe(context);
+    setValues(() => 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) => {
+          setValues((previous) => {
+            return {
+              ...previous,
+              [key]: next
+            };
+          });
+        }));
+      } catch {
+      }
+    }
+    onCleanup(() => {
+      for (const unsubscribe of unsubscribes) {
+        unsubscribe();
+      }
+    });
+  }));
+  return values;
+};
+
+export { createFlag, createFlags };

package/dist/packem_shared/createMutator-foSnPJPt.mjs

@@ -0,0 +1,24 @@
+import { createMutatorRunner } from '@lunora/client';
+import { createSignal } from 'solid-js';
+
+const createMutator = (handle) => {
+  const [error, setError] = createSignal(void 0);
+  const [pending, setPending] = createSignal(false);
+  const {
+    mutate,
+    reset
+  } = createMutatorRunner(handle, {
+    setError,
+    setPending
+  });
+  const isError = () => error() !== void 0;
+  return {
+    error,
+    isError,
+    mutate,
+    pending,
+    reset
+  };
+};
+
+export { createMutator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/solid",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "description": "SolidJS adapter for Lunora — live queries, optimistic mutations, and reactive loaders",
   "keywords": [
     "cloudflare",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.4",
+    "@lunora/client": "1.0.0-alpha.5",
     "@lunora/ratelimit": "1.0.0-alpha.3"
   },
   "peerDependencies": {