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

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

@@ -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>;
@@ -336,4 +373,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 PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };

package/dist/index.d.ts

@@ -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>;
@@ -336,4 +373,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 PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 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 { createInfiniteQuery, createPaginatedQuery } from './packem_shared/createInfiniteQuery-DyMvQ2Qy.mjs';
 export { createPresence } from './packem_shared/createPresence-DiAak1Jw.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/solid",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.6",
   "description": "SolidJS adapter for Lunora — live queries, optimistic mutations, and reactive loaders",
   "keywords": [
     "cloudflare",