@razakalpha/convngx 0.2.0 → 0.2.2

package/src/lib/core/helpers.ts

@@ -0,0 +1,60 @@
+/**
+ * Internal helpers for ConvexAngularClient.
+ * NOTE: Pure refactor; functionality unchanged.
+ */
+
+export const AUTH_KEY = 'convex:jwt';
+export const AUTH_CH = 'convex-auth';
+
+/** Decode JWT exp claim (ms). Returns 0 if invalid. */
+export function jwtExpMs(jwt: string): number {
+  try {
+    const payload = JSON.parse(atob(jwt.split('.')[1] || ''));
+    return typeof payload?.exp === 'number' ? payload.exp * 1000 : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Canonical JSON stringify for stable de-dupe keys. */
+export function stableStringify(input: unknown): string {
+  const seen = new WeakSet<object>();
+  const norm = (v: any): any => {
+    if (v === null || typeof v !== 'object') return v;
+    if (seen.has(v)) return v;
+    seen.add(v);
+    if (Array.isArray(v)) return v.map(norm);
+    return Object.keys(v)
+      .sort()
+      .reduce((acc: any, k) => {
+        acc[k] = norm(v[k]);
+        return acc;
+      }, {});
+  };
+  return JSON.stringify(norm(input));
+}
+
+/** sessionStorage helpers (some browsers may throw on access) */
+export const safeSession = {
+  get: (k: string): string | null => {
+    try {
+      return typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(k) : null;
+    } catch {
+      return null;
+    }
+  },
+  set: (k: string, v: string) => {
+    try {
+      if (typeof sessionStorage !== 'undefined') sessionStorage.setItem(k, v);
+    } catch {
+      /* no-op */
+    }
+  },
+  del: (k: string) => {
+    try {
+      if (typeof sessionStorage !== 'undefined') sessionStorage.removeItem(k);
+    } catch {
+      /* no-op */
+    }
+  },
+};

package/src/lib/core/inject-convex.token.ts

@@ -0,0 +1,12 @@
+/**
+* Injection token and helper for accessing the Convex client from DI.
+* Keep this tiny and stable — many helpers rely on it.
+*/
+import { inject, InjectionToken } from '@angular/core';
+import { ConvexAngularClient } from './convex-angular-client';
+
+/** DI token for the configured ConvexAngularClient instance */
+export const CONVEX = new InjectionToken<ConvexAngularClient>('CONVEX');
+
+/** Convenience helper to inject the Convex client */
+export const injectConvex = () => inject(CONVEX);

package/src/lib/core/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared types for Convex Angular core.
+ * Pure extraction for readability; no behavior changes.
+ */
+
+/** Auth token fetcher used by ConvexAngularClient.setAuth */
+export type FetchAccessToken = (o: { forceRefreshToken: boolean }) => Promise<string | null>;
+
+/** Snapshot of current auth state (token presence-based) */
+export type AuthSnapshot = {
+  isAuthenticated: boolean;
+  token: string | null;
+  exp?: number;
+};

package/src/lib/resources/action.resource.ts

@@ -0,0 +1,153 @@
+// convex-action-resource.ts
+import {
+  ResourceRef,
+  ResourceStreamItem,
+  computed,
+  resource,
+  signal,
+  type Signal,
+} from '@angular/core';
+import { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import { injectConvex } from '../core/inject-convex.token';
+
+export type ActionRef = FunctionReference<'action'>;
+type NoArgsAction = ActionRef & { _args: Record<string, never> };
+type IfEmptyArgs<A extends ActionRef, TIfEmpty, TIfNot> = keyof A['_args'] extends never
+  ? TIfEmpty
+  : TIfNot;
+
+export interface ConvexActionOptions<A extends ActionRef> {
+  onSuccess?: (data: FunctionReturnType<A>) => void;
+  onError?: (err: Error) => void;
+  /** concurrency: queue = sequential, drop = ignore while inflight, replace = prefer latest */
+  mode?: 'queue' | 'drop' | 'replace';
+  /** simple retry */
+  retries?: number;
+  retryDelayMs?: (attempt: number) => number;
+}
+
+type RunFn<A extends ActionRef> = IfEmptyArgs<
+  A,
+  (args?: FunctionArgs<A>) => Promise<FunctionReturnType<A>>,
+  (args: FunctionArgs<A>) => Promise<FunctionReturnType<A>>
+>;
+
+export interface ConvexActionResource<A extends ActionRef> {
+  run: RunFn<A>;
+  state: ResourceRef<FunctionReturnType<A> | undefined>;
+  data: Signal<FunctionReturnType<A> | undefined>;
+  error: Signal<Error | undefined>;
+  isRunning: Signal<boolean>;
+  reset(): void;
+}
+
+/** Overloads for nice run() arg ergonomics */
+export function convexActionResource<A extends NoArgsAction>(
+  action: A,
+  opts?: ConvexActionOptions<A>,
+): ConvexActionResource<A>;
+export function convexActionResource<A extends ActionRef>(
+  action: A,
+  opts?: ConvexActionOptions<A>,
+): ConvexActionResource<A>;
+
+/** Single impl */
+export function convexActionResource<A extends ActionRef>(
+  action: A,
+  opts?: ConvexActionOptions<A>,
+): ConvexActionResource<A> {
+  const convex = injectConvex();
+  const isRunning = signal(false);
+  const inflight = signal<Promise<unknown> | undefined>(undefined);
+  const pending = new Map<number, { resolve: (v: any) => void; reject: (e: any) => void }>();
+  const trigger = signal<{ id: number; args: FunctionArgs<A> } | undefined>(undefined);
+  let seq = 0;
+
+  const state = resource<
+    FunctionReturnType<A> | undefined,
+    { id: number; args: FunctionArgs<A> } | undefined
+  >({
+    params: computed(() => trigger()),
+    stream: async ({ params, abortSignal }) => {
+      const out = signal<ResourceStreamItem<FunctionReturnType<A> | undefined>>({
+        value: undefined,
+      });
+      if (!params) return out;
+
+      const done = () => {
+        const w = pending.get(params.id);
+        if (w) pending.delete(params.id);
+      };
+
+      const runOnce = async () => {
+        let attempt = 0;
+        const retries = opts?.retries ?? 0;
+        const delay = (n: number) =>
+          new Promise((r) => setTimeout(r, opts?.retryDelayMs?.(n) ?? 500 * n));
+
+        while (true) {
+          try {
+            const res = await convex.action(action, params.args);
+            if (!abortSignal.aborted) {
+              out.set({ value: res });
+              opts?.onSuccess?.(res);
+              pending.get(params.id)?.resolve(res);
+            }
+            done();
+            return;
+          } catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            if (!abortSignal.aborted) out.set({ error: err });
+            if (attempt >= retries) {
+              opts?.onError?.(err);
+              pending.get(params.id)?.reject(err);
+              done();
+              return;
+            }
+            attempt++;
+            await delay(attempt);
+          }
+        }
+      };
+
+      isRunning.set(true);
+      try {
+        const p = runOnce();
+        inflight.set(p);
+        await p;
+      } finally {
+        if (!abortSignal.aborted) isRunning.set(false);
+        if (inflight() && (await inflight()) === undefined) inflight.set(undefined);
+      }
+
+      return out;
+    },
+  });
+
+  const data = computed(() => state.value());
+  const error = computed(() => state.error());
+
+  const run: RunFn<A> = (async (args?: FunctionArgs<A>) => {
+    const job = { id: ++seq, args: (args ?? ({} as any)) as FunctionArgs<A> };
+
+    if (opts?.mode === 'drop' && inflight()) {
+      return inflight() as Promise<FunctionReturnType<A>>;
+    }
+    if (opts?.mode === 'queue' && inflight()) {
+      await inflight();
+    }
+
+    const promise = new Promise<FunctionReturnType<A>>((resolve, reject) => {
+      pending.set(job.id, { resolve, reject });
+    });
+
+    trigger.set(job); // "replace" naturally supersedes older emissions
+    return promise;
+  }) as RunFn<A>;
+
+  const reset = () => {
+    (state as any).reset?.();
+  };
+
+  return { run, state, data, error, isRunning: isRunning.asReadonly(), reset };
+}

package/src/lib/resources/live.resource.ts

@@ -0,0 +1,149 @@
+// convex-resource.ts
+import {
+  ResourceRef,
+  ResourceStreamItem,
+  computed,
+  inject,
+  resource,
+  signal,
+  InjectionToken,
+  Provider,
+} from '@angular/core';
+import { FunctionReference, FunctionReturnType } from 'convex/server';
+import { injectConvex } from '../core/inject-convex.token';
+
+export type QueryRef = FunctionReference<'query'>;
+export type KeepMode = 'none' | 'last';
+
+export interface ConvexResourceOptions {
+  keep?: KeepMode;
+}
+
+const DEFAULTS: Required<ConvexResourceOptions> = { keep: 'last' };
+
+export const CONVEX_RESOURCE_OPTIONS = new InjectionToken<Required<ConvexResourceOptions>>(
+  'CONVEX_RESOURCE_OPTIONS',
+  { factory: () => DEFAULTS },
+);
+
+export function provideConvexResourceOptions(opts: Partial<ConvexResourceOptions>): Provider {
+  return { provide: CONVEX_RESOURCE_OPTIONS, useValue: { ...DEFAULTS, ...opts } };
+}
+
+// “no-args” queries have `_args` compatible with {}
+type NoArgsQuery = QueryRef & { _args: Record<string, never> };
+
+/** Overloads */
+export function convexLiveResource<Q extends NoArgsQuery>(
+  query: Q,
+  opts?: ConvexResourceOptions,
+): ResourceRef<FunctionReturnType<Q> | undefined>;
+export function convexLiveResource<Q extends NoArgsQuery>(
+  query: Q,
+  params: () => {} | undefined,
+  opts?: ConvexResourceOptions,
+): ResourceRef<FunctionReturnType<Q> | undefined>;
+export function convexLiveResource<Q extends QueryRef>(
+  query: Q,
+  params: () => Q['_args'] | undefined,
+  opts?: ConvexResourceOptions,
+): ResourceRef<FunctionReturnType<Q> | undefined>;
+
+/** Impl */
+export function convexLiveResource<Q extends QueryRef>(
+  query: Q,
+  a?: (() => Q['_args'] | undefined) | ConvexResourceOptions,
+  b?: ConvexResourceOptions,
+): ResourceRef<FunctionReturnType<Q> | undefined> {
+  const convex = injectConvex();
+  const global = inject(CONVEX_RESOURCE_OPTIONS);
+  const keepMode = (typeof a === 'function' ? b : a)?.keep ?? global.keep;
+
+  const paramsFactory: (() => Q['_args'] | undefined) | undefined =
+    typeof a === 'function' ? a : undefined;
+
+  const lastGlobal = signal<FunctionReturnType<Q> | undefined>(undefined);
+
+  const argsSig = computed<Q['_args'] | undefined>(() => {
+    if (!paramsFactory) return {} as Q['_args']; // no-args: always enabled
+    return paramsFactory();
+  });
+
+  // --- reload tagging ---
+  const reloadStamp = signal(0); // increments only when .reload() is called
+  let lastSeenReload = 0; // compared inside stream to detect reload
+
+  type ParamEnvelope = { args: Q['_args'] | undefined; __r: number } | undefined;
+
+  const request = computed<ParamEnvelope>(() => ({
+    args: argsSig(),
+    __r: reloadStamp(),
+  }));
+
+  const base = resource<FunctionReturnType<Q> | undefined, ParamEnvelope>({
+    params: request,
+    stream: async ({ params, abortSignal }) => {
+      const s = signal<ResourceStreamItem<FunctionReturnType<Q> | undefined>>({
+        value: keepMode === 'last' ? lastGlobal() : undefined,
+      });
+
+      if (!params || !params.args) return s; // gated
+      const isReload = params.__r !== lastSeenReload;
+      lastSeenReload = params.__r;
+
+      // One-shot fetch: ONLY on reload
+      if (isReload) {
+        convex
+          .query(query, params.args)
+          .then((next) => {
+            if (abortSignal.aborted) return;
+            s.set({ value: next });
+            lastGlobal.set(next);
+          })
+          .catch((err) => {
+            if (abortSignal.aborted) return;
+            s.set({ error: err as Error });
+          });
+      }
+
+      // Live subscription (always)
+      const w = convex.watchQuery(query, params.args as Q['_args']);
+
+      try {
+        const local = w.localQueryResult();
+        if (local !== undefined) {
+          s.set({ value: local });
+          lastGlobal.set(local);
+        }
+      } catch (err) {
+        s.set({ error: err as Error });
+      }
+
+      const off = w.onUpdate(() => {
+        try {
+          const next = w.localQueryResult();
+          s.set({ value: next });
+          lastGlobal.set(next);
+        } catch (err) {
+          s.set({ error: err as Error });
+        }
+      });
+
+      abortSignal.addEventListener('abort', () => off(), { once: true });
+      return s;
+    },
+  });
+
+  // Wrap to bump reloadStamp only when user calls reload()
+  const origReload = base.reload.bind(base);
+
+  const wrapped: ResourceRef<FunctionReturnType<Q> | undefined> = {
+    ...base,
+    reload: () => {
+      reloadStamp.set(reloadStamp() + 1);
+      return origReload();
+    },
+  };
+
+  return wrapped;
+}

package/src/lib/resources/mutation.resource.ts

@@ -0,0 +1,171 @@
+// convex-mutation-resource.ts
+import {
+  ResourceRef,
+  ResourceStreamItem,
+  computed,
+  resource,
+  signal,
+  type Signal,
+} from '@angular/core';
+import type { OptimisticUpdate } from 'convex/browser';
+import { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import { injectConvex } from '../core/inject-convex.token';
+
+export type MutationRef = FunctionReference<'mutation'>;
+type NoArgsMutation = MutationRef & { _args: Record<string, never> };
+type IfEmptyArgs<M extends MutationRef, TIfEmpty, TIfNot> = keyof M['_args'] extends never
+  ? TIfEmpty
+  : TIfNot;
+
+export interface ConvexMutationOptions<M extends MutationRef> {
+  optimisticUpdate?: OptimisticUpdate<FunctionArgs<M>>;
+  onSuccess?: (data: FunctionReturnType<M>) => void;
+  onError?: (err: Error) => void;
+  /** concurrency: queue = sequential, drop = ignore while inflight, replace = prefer latest */
+  mode?: 'queue' | 'drop' | 'replace';
+  /** simple retry */
+  retries?: number;
+  retryDelayMs?: (attempt: number) => number;
+}
+
+type RunFn<M extends MutationRef> = IfEmptyArgs<
+  M,
+  (args?: FunctionArgs<M>) => Promise<FunctionReturnType<M>>,
+  (args: FunctionArgs<M>) => Promise<FunctionReturnType<M>>
+>;
+
+export interface ConvexMutationResource<M extends MutationRef> {
+  /** imperative trigger */
+  run: RunFn<M>;
+  /** resource-shaped state (bind in templates if you like) */
+  state: ResourceRef<FunctionReturnType<M> | undefined>;
+  /** convenience signals */
+  data: Signal<FunctionReturnType<M> | undefined>;
+  error: Signal<Error | undefined>;
+  isRunning: Signal<boolean>;
+  reset(): void;
+}
+
+/** Overloads for nice run() arg ergonomics */
+export function convexMutationResource<M extends NoArgsMutation>(
+  mutation: M,
+  opts?: ConvexMutationOptions<M>,
+): ConvexMutationResource<M>;
+export function convexMutationResource<M extends MutationRef>(
+  mutation: M,
+  opts?: ConvexMutationOptions<M>,
+): ConvexMutationResource<M>;
+
+/** Single impl */
+export function convexMutationResource<M extends MutationRef>(
+  mutation: M,
+  opts?: ConvexMutationOptions<M>,
+): ConvexMutationResource<M> {
+  const convex = injectConvex();
+  const isRunning = signal(false);
+  const pending = new Map<number, { resolve: (v: any) => void; reject: (e: any) => void }>();
+  const inflight = signal<Promise<unknown> | undefined>(undefined);
+  const trigger = signal<{ id: number; args: FunctionArgs<M> } | undefined>(undefined);
+  let seq = 0;
+
+  const state = resource<
+    FunctionReturnType<M> | undefined,
+    { id: number; args: FunctionArgs<M> } | undefined
+  >({
+    params: computed(() => trigger()),
+    stream: async ({ params, abortSignal }) => {
+      const out = signal<ResourceStreamItem<FunctionReturnType<M> | undefined>>({
+        value: undefined,
+      });
+      if (!params) return out;
+
+      const done = () => {
+        // clean out waiter if still present
+        const w = pending.get(params.id);
+        if (w) pending.delete(params.id);
+      };
+
+      const runOnce = async () => {
+        let attempt = 0;
+        const retries = opts?.retries ?? 0;
+        const delay = (n: number) =>
+          new Promise((r) => setTimeout(r, opts?.retryDelayMs?.(n) ?? 500 * n));
+
+        // NB: Convex mutations don’t support abort; we still observe abortSignal to stop emitting.
+        // We *do not* call mutation again on aborted; we just stop updating UI.
+        // If you choose mode: 'replace', older runs get superseded by newer trigger()s.
+        // That’s the main “cancellation” we can mimic here.
+        while (true) {
+          try {
+            const res = await convex.mutation(mutation, params.args, {
+              optimisticUpdate: opts?.optimisticUpdate,
+            });
+            if (!abortSignal.aborted) {
+              out.set({ value: res });
+              opts?.onSuccess?.(res);
+              pending.get(params.id)?.resolve(res);
+            }
+            done();
+            return;
+          } catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            if (!abortSignal.aborted) {
+              out.set({ error: err });
+            }
+            if (attempt >= retries) {
+              opts?.onError?.(err);
+              pending.get(params.id)?.reject(err);
+              done();
+              return;
+            }
+            attempt++;
+            await delay(attempt);
+          }
+        }
+      };
+
+      isRunning.set(true);
+      try {
+        const p = runOnce();
+        inflight.set(p);
+        await p;
+      } finally {
+        if (!abortSignal.aborted) isRunning.set(false);
+        if (inflight() && (await inflight()) === undefined) inflight.set(undefined);
+      }
+
+      return out;
+    },
+  });
+
+  const data = computed(() => state.value());
+  const error = computed(() => state.error());
+
+  const run: RunFn<M> = (async (args?: FunctionArgs<M>) => {
+    const job = { id: ++seq, args: (args ?? ({} as any)) as FunctionArgs<M> };
+
+    if (opts?.mode === 'drop' && inflight()) {
+      // return the inflight promise if present (best-effort)
+      return inflight() as Promise<any>;
+    }
+
+    if (opts?.mode === 'queue' && inflight()) {
+      await inflight();
+    }
+
+    const promise = new Promise<FunctionReturnType<M>>((resolve, reject) => {
+      pending.set(job.id, { resolve, reject });
+    });
+
+    // "replace": push new job; older job’s UI will be superseded by the next emission
+    trigger.set(job);
+    return promise;
+  }) as RunFn<M>;
+
+  const reset = () => {
+    // clear UI state; does not affect in-flight promise
+    (state as any).reset?.(); // safe if Angular adds reset later; otherwise ignore
+  };
+
+  return { run, state, data, error, isRunning: isRunning.asReadonly(), reset };
+}

package/src/lib/setup/convex-angular.providers.ts

@@ -0,0 +1,66 @@
+import { Provider } from '@angular/core';
+import { AUTH_CLIENT, provideAuthClient, type AuthClient } from '../auth/auth-client.provider';
+import { provideConvexBetterAuth } from '../auth/convex-better-auth.provider';
+import { provideConvexResourceOptions, type KeepMode } from '../resources/live.resource';
+
+export interface ConvexAngularOptions {
+  /** Convex deployment URL, e.g. https://xxx.convex.cloud */
+  convexUrl: string;
+  /** Better Auth base URL (convex site url), e.g. https://xxx.convex.site */
+  authBaseURL: string;
+  /** Skew before JWT expiry to refresh token */
+  authSkewMs?: number;
+  /** Default keep mode for live resources ('last' | 'none') */
+  keep?: KeepMode;
+  /**
+   * Optional: user-provided Better Auth client.
+   * Must include convexClient() and crossDomainClient() plugins.
+   */
+  authClient?: AuthClient;
+}
+
+/**
+ * Single entry-point provider to wire Convex + Better Auth + resource defaults.
+ * Behavior:
+ * - If opts.authClient is provided, we use it (and verify required plugins).
+ * - Else we create a default Better Auth client using authBaseURL with required plugins.
+ */
+export function provideConvexAngular(opts: ConvexAngularOptions): Provider[] {
+  const providers: Provider[] = [];
+
+  if (opts.authClient) {
+    providers.push({
+      provide: AUTH_CLIENT,
+      useFactory: () => {
+        const c = opts.authClient as AuthClient;
+        const hasConvex = typeof c.convex?.token === 'function';
+        const hasCross = typeof c.crossDomain?.oneTimeToken?.verify === 'function';
+        if (!hasConvex || !hasCross) {
+          throw new Error(
+            'Provided AUTH client is missing required plugins: convexClient() and crossDomainClient().',
+          );
+        }
+        return c;
+      },
+    });
+  } else {
+    // Default client with known plugin set (convex + crossDomain)
+    providers.push(
+      provideAuthClient({
+        baseURL: opts.authBaseURL,
+      }),
+    );
+  }
+
+  providers.push(
+    ...provideConvexBetterAuth({
+      convexUrl: opts.convexUrl,
+      authSkewMs: opts.authSkewMs,
+    }),
+  );
+
+  if (opts.keep) {
+    providers.push(provideConvexResourceOptions({ keep: opts.keep }));
+  }
+  return providers;
+}

package/src/public-api.ts

@@ -0,0 +1,19 @@
+/*
+ * Public API Surface of convex-angular
+ */
+
+// Core client and DI token
+export * from './lib/core/convex-angular-client';
+export * from './lib/core/inject-convex.token';
+
+// One-call setup provider (combine common providers)
+export * from './lib/setup/convex-angular.providers';
+
+// Better Auth + Convex provider
+export * from './lib/auth/convex-better-auth.provider';
+export * from './lib/auth/auth-client.provider';
+
+// Angular resource helpers for Convex
+export * from './lib/resources/live.resource';
+export * from './lib/resources/mutation.resource';
+export * from './lib/resources/action.resource';

package/tsconfig.lib.json

@@ -0,0 +1,20 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "**/*.spec.ts",
+    "src/lib/auth.ts"
+  ]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}