@vishalsharma7nov/react-native-proto 0.2.2

package/src/native-grpc/index.ts

@@ -0,0 +1,302 @@
+import { ProtoClientError } from '../errors';
+import type { ResolvedTransportConfig } from '../transport';
+import type { CodecRegistry, StreamCallInput, UnaryCallInput } from '../types';
+
+type NativeBridge = {
+  unary: (input: {
+    baseUrl: string;
+    rpcPath: string;
+    requestBytes: Uint8Array;
+    headers: Record<string, string>;
+    timeoutMs: number;
+  }) => Promise<Uint8Array>;
+  stream?: (input: {
+    baseUrl: string;
+    rpcPath: string;
+    requestBytes: Uint8Array;
+    headers: Record<string, string>;
+    timeoutMs: number;
+  }) => AsyncIterable<Uint8Array>;
+};
+
+type NativeGrpcModule = {
+  unary: (
+    baseUrl: string,
+    rpcPath: string,
+    requestBase64: string,
+    headersJson: string,
+    timeoutMs: number
+  ) => Promise<string>;
+  isAvailable?: () => Promise<boolean>;
+};
+
+declare global {
+  // Optional native module injected by the host app / TurboModule
+  // eslint-disable-next-line no-var
+  var __REACT_NATIVE_PROTO_NATIVE_GRPC__: NativeBridge | undefined;
+}
+
+type BufferLike = {
+  from(
+    data: string | Uint8Array,
+    encoding?: string
+  ): Uint8Array & { toString(encoding: string): string };
+};
+
+function getGlobalBuffer(): BufferLike | undefined {
+  const candidate = (globalThis as { Buffer?: BufferLike }).Buffer;
+  return typeof candidate?.from === 'function' ? candidate : undefined;
+}
+
+/** Encode bytes to base64 without requiring a Buffer polyfill on RN. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  const BufferCtor = getGlobalBuffer();
+  if (BufferCtor) {
+    return BufferCtor.from(bytes).toString('base64');
+  }
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 1) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  if (typeof btoa !== 'function') {
+    throw new Error('base64 encode unavailable (no Buffer or btoa)');
+  }
+  return btoa(binary);
+}
+
+/** Decode base64 to bytes without requiring a Buffer polyfill on RN. */
+export function base64ToBytes(base64: string): Uint8Array {
+  const BufferCtor = getGlobalBuffer();
+  if (BufferCtor) {
+    const buf = BufferCtor.from(base64, 'base64');
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+  if (typeof atob !== 'function') {
+    throw new Error('base64 decode unavailable (no Buffer or atob)');
+  }
+  const binary = atob(base64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+
+function getNativeModule(): NativeGrpcModule | undefined {
+  try {
+    // Optional peer — do not hard-depend at module load time.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rn = require('react-native') as {
+      NativeModules?: { ReactNativeProtoNativeGrpc?: NativeGrpcModule };
+    };
+    const mod = rn.NativeModules?.ReactNativeProtoNativeGrpc;
+    if (mod && typeof mod.unary === 'function') {
+      return mod;
+    }
+  } catch {
+    // Not running in React Native, or NativeModules unavailable.
+  }
+  return undefined;
+}
+
+function createBridgeFromNativeModule(mod: NativeGrpcModule): NativeBridge {
+  return {
+    async unary({ baseUrl, rpcPath, requestBytes, headers, timeoutMs }) {
+      const responseBase64 = await mod.unary(
+        baseUrl,
+        rpcPath,
+        bytesToBase64(requestBytes),
+        JSON.stringify(headers ?? {}),
+        timeoutMs
+      );
+      if (typeof responseBase64 !== 'string') {
+        throw new Error('Native unary did not return a base64 string');
+      }
+      return base64ToBytes(responseBase64);
+    },
+  };
+}
+
+/**
+ * Wire `NativeModules.ReactNativeProtoNativeGrpc` into
+ * `global.__REACT_NATIVE_PROTO_NATIVE_GRPC__` for the JS transport layer.
+ * Returns true when the bridge was installed.
+ */
+export function installNativeGrpcBridgeFromNativeModule(): boolean {
+  const mod = getNativeModule();
+  if (!mod) {
+    return false;
+  }
+  globalThis.__REACT_NATIVE_PROTO_NATIVE_GRPC__ =
+    createBridgeFromNativeModule(mod);
+  return true;
+}
+
+function getBridge(): NativeBridge {
+  const existing = globalThis.__REACT_NATIVE_PROTO_NATIVE_GRPC__;
+  if (existing && typeof existing.unary === 'function') {
+    return existing;
+  }
+
+  if (installNativeGrpcBridgeFromNativeModule()) {
+    const installed = globalThis.__REACT_NATIVE_PROTO_NATIVE_GRPC__;
+    if (installed && typeof installed.unary === 'function') {
+      return installed;
+    }
+  }
+
+  throw new ProtoClientError({
+    code: 'UNSUPPORTED',
+    message:
+      'Native gRPC bridge is not installed. Link the native module or use transport "http" / "connect".',
+  });
+}
+
+async function headersFromConfig(
+  config: ResolvedTransportConfig,
+  rpcPath: string
+): Promise<Record<string, string>> {
+  if (!config.getHeaders) {
+    return {};
+  }
+  try {
+    return await config.getHeaders();
+  } catch (cause) {
+    throw new ProtoClientError({
+      code: 'INVALID_ARGUMENT',
+      message: 'getHeaders() failed',
+      rpcPath,
+      cause,
+    });
+  }
+}
+
+export async function nativeGrpcUnary(
+  config: ResolvedTransportConfig,
+  codecs: CodecRegistry,
+  input: UnaryCallInput
+): Promise<Record<string, unknown>> {
+  const bridge = getBridge();
+  const { entry, request } = input;
+  const requestCodec = codecs.get(entry.requestType);
+  const responseCodec = codecs.get(entry.responseType);
+  if (!requestCodec || !responseCodec) {
+    throw new ProtoClientError({
+      code: 'INVALID_ARGUMENT',
+      message: `Missing codec for ${entry.requestType} or ${entry.responseType}`,
+      rpcPath: entry.rpcPath,
+    });
+  }
+
+  let requestBytes: Uint8Array;
+  try {
+    requestBytes = requestCodec.encode(request ?? {});
+  } catch (cause) {
+    throw new ProtoClientError({
+      code: 'INVALID_ARGUMENT',
+      message: `Failed to encode request for ${entry.rpcPath}`,
+      rpcPath: entry.rpcPath,
+      cause,
+    });
+  }
+
+  const headers = await headersFromConfig(config, entry.rpcPath);
+
+  let responseBytes: Uint8Array;
+  try {
+    responseBytes = await bridge.unary({
+      baseUrl: config.baseUrl,
+      rpcPath: entry.rpcPath,
+      requestBytes,
+      headers,
+      timeoutMs: config.timeoutMs,
+    });
+  } catch (cause) {
+    throw new ProtoClientError({
+      code: 'RPC',
+      message: `Native gRPC call failed for ${entry.rpcPath}`,
+      rpcPath: entry.rpcPath,
+      cause,
+      retryable: true,
+    });
+  }
+
+  if (responseBytes.byteLength > config.maxResponseBytes) {
+    throw new ProtoClientError({
+      code: 'PAYLOAD_TOO_LARGE',
+      message: `Native response exceeds maxResponseBytes ${config.maxResponseBytes}`,
+      rpcPath: entry.rpcPath,
+    });
+  }
+
+  try {
+    return responseCodec.decode(responseBytes);
+  } catch (cause) {
+    throw new ProtoClientError({
+      code: 'DECODE',
+      message: `Failed to decode native gRPC response for ${entry.rpcPath}`,
+      rpcPath: entry.rpcPath,
+      cause,
+    });
+  }
+}
+
+export async function* nativeGrpcStream(
+  config: ResolvedTransportConfig,
+  codecs: CodecRegistry,
+  input: StreamCallInput
+): AsyncGenerator<Record<string, unknown>, void, undefined> {
+  const bridge = getBridge();
+  if (typeof bridge.stream !== 'function') {
+    throw new ProtoClientError({
+      code: 'UNSUPPORTED',
+      message: 'Native gRPC bridge does not implement streaming',
+      rpcPath: input.entry.rpcPath,
+    });
+  }
+
+  const { entry, request } = input;
+  const requestCodec = codecs.get(entry.requestType);
+  const responseCodec = codecs.get(entry.responseType);
+  if (!requestCodec || !responseCodec) {
+    throw new ProtoClientError({
+      code: 'INVALID_ARGUMENT',
+      message: `Missing codec for ${entry.requestType} or ${entry.responseType}`,
+      rpcPath: entry.rpcPath,
+    });
+  }
+
+  const requestBytes = requestCodec.encode(request ?? {});
+  const headers = await headersFromConfig(config, entry.rpcPath);
+  const frames = bridge.stream({
+    baseUrl: config.baseUrl,
+    rpcPath: entry.rpcPath,
+    requestBytes,
+    headers,
+    timeoutMs: config.timeoutMs,
+  });
+
+  for await (const frame of frames) {
+    if (frame.byteLength > config.maxResponseBytes) {
+      throw new ProtoClientError({
+        code: 'PAYLOAD_TOO_LARGE',
+        message: 'Native stream frame exceeds maxResponseBytes',
+        rpcPath: entry.rpcPath,
+      });
+    }
+    const message = responseCodec.decode(frame);
+    if (input.onMessage) {
+      input.onMessage(message);
+    }
+    yield message;
+  }
+}
+
+export function isNativeGrpcAvailable(): boolean {
+  if (
+    typeof globalThis.__REACT_NATIVE_PROTO_NATIVE_GRPC__?.unary === 'function'
+  ) {
+    return true;
+  }
+  return getNativeModule() != null;
+}

package/src/offline-queue.ts

@@ -0,0 +1,160 @@
+import { ProtoClientError } from './errors';
+
+export type QueuedMutation = {
+  id: string;
+  label: string;
+  run: () => Promise<unknown>;
+  enqueuedAt: number;
+};
+
+export type OfflineQueueOptions = {
+  /** Max queued items (default 50) */
+  maxSize?: number;
+  /** Called whenever queue length changes */
+  onChange?: (size: number) => void;
+  /** Persist/rehydrate hooks for app storage */
+  storage?: {
+    load: () => Promise<QueuedMutation[]> | QueuedMutation[];
+    save: (items: QueuedMutation[]) => Promise<void> | void;
+  };
+};
+
+/**
+ * Queue failed (or deferred) mutations and flush when back online.
+ * Does not auto-detect network — call `setOnline(true/false)` or `flush()` yourself.
+ */
+export class OfflineMutationQueue {
+  private items: QueuedMutation[] = [];
+  private readonly maxSize: number;
+  private readonly onChange?: (size: number) => void;
+  private readonly storage?: OfflineQueueOptions['storage'];
+  private online = true;
+  private flushing = false;
+
+  constructor(options: OfflineQueueOptions = {}) {
+    this.maxSize = options.maxSize ?? 50;
+    this.onChange = options.onChange;
+    this.storage = options.storage;
+  }
+
+  async hydrate(): Promise<void> {
+    if (!this.storage) return;
+    const loaded = await this.storage.load();
+    this.items = Array.isArray(loaded) ? loaded.slice(0, this.maxSize) : [];
+    this.emit();
+  }
+
+  setOnline(online: boolean): void {
+    this.online = online;
+    if (online) {
+      void this.flush();
+    }
+  }
+
+  isOnline(): boolean {
+    return this.online;
+  }
+
+  size(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Run immediately when online; otherwise enqueue and resolve after flush.
+   */
+  async runOrEnqueue<T>(
+    label: string,
+    run: () => Promise<T>
+  ): Promise<T> {
+    if (this.online) {
+      return run();
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      if (this.items.length >= this.maxSize) {
+        reject(
+          new ProtoClientError({
+            code: 'INVALID_ARGUMENT',
+            message: `Offline queue is full (max ${this.maxSize})`,
+          })
+        );
+        return;
+      }
+
+      const id = `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+      this.items.push({
+        id,
+        label,
+        enqueuedAt: Date.now(),
+        run: async () => {
+          const result = await run();
+          resolve(result);
+          return result;
+        },
+      });
+      this.emit();
+      void this.persist();
+    });
+  }
+
+  enqueue(label: string, run: () => Promise<unknown>): string {
+    if (this.items.length >= this.maxSize) {
+      throw new ProtoClientError({
+        code: 'INVALID_ARGUMENT',
+        message: `Offline queue is full (max ${this.maxSize})`,
+      });
+    }
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    this.items.push({ id, label, run, enqueuedAt: Date.now() });
+    this.emit();
+    void this.persist();
+    return id;
+  }
+
+  async flush(): Promise<{ ok: number; failed: number }> {
+    if (this.flushing) {
+      return { ok: 0, failed: 0 };
+    }
+    this.flushing = true;
+    let ok = 0;
+    let failed = 0;
+
+    try {
+      while (this.items.length > 0 && this.online) {
+        const item = this.items[0];
+        if (!item) break;
+        try {
+          await item.run();
+          this.items.shift();
+          ok += 1;
+          this.emit();
+          await this.persist();
+        } catch {
+          failed += 1;
+          break;
+        }
+      }
+    } finally {
+      this.flushing = false;
+    }
+
+    return { ok, failed };
+  }
+
+  clear(): void {
+    this.items = [];
+    this.emit();
+    void this.persist();
+  }
+
+  private emit(): void {
+    if (this.onChange) {
+      this.onChange(this.items.length);
+    }
+  }
+
+  private async persist(): Promise<void> {
+    if (!this.storage) return;
+    await this.storage.save(this.items);
+  }
+}

package/src/path-templates.ts

@@ -0,0 +1,65 @@
+import type { MethodMapEntry } from './types';
+
+export type PathTemplatePreset =
+  | 'connect'
+  | 'grpc-web'
+  | 'envoy'
+  | 'grpc-gateway'
+  | 'restish';
+
+function packagePrefix(entry: MethodMapEntry): string {
+  return entry.packageName ? `${entry.packageName}.` : '';
+}
+
+function lowerFirst(value: string): string {
+  if (!value) return value;
+  return value.charAt(0).toLowerCase() + value.slice(1);
+}
+
+/**
+ * Built-in path builders for common gateways and proxies.
+ *
+ * - connect / grpc-web / envoy: `/{package}.{Service}/{Method}`
+ * - grpc-gateway: `/{package}.{Service}/{Method}` (HTTP body RPC style)
+ * - restish: `/v1/{service}/{method}` (lowercase camel segments)
+ */
+export function createPathForMethod(
+  preset: PathTemplatePreset = 'connect'
+): (entry: MethodMapEntry) => string {
+  switch (preset) {
+    case 'restish':
+      return (entry) =>
+        `/v1/${lowerFirst(entry.serviceName)}/${lowerFirst(entry.methodName)}`;
+    case 'grpc-gateway':
+    case 'connect':
+    case 'grpc-web':
+    case 'envoy':
+    default:
+      return (entry) =>
+        `/${packagePrefix(entry)}${entry.serviceName}/${entry.methodName}`;
+  }
+}
+
+/**
+ * Custom template. Placeholders:
+ * `{package}` `{service}` `{method}` `{rpcPath}`
+ * `{serviceCamel}` `{methodCamel}`
+ */
+export function pathFromTemplate(
+  template: string
+): (entry: MethodMapEntry) => string {
+  return (entry) =>
+    template
+      .split('{package}')
+      .join(entry.packageName)
+      .split('{service}')
+      .join(entry.serviceName)
+      .split('{method}')
+      .join(entry.methodName)
+      .split('{rpcPath}')
+      .join(entry.rpcPath)
+      .split('{serviceCamel}')
+      .join(lowerFirst(entry.serviceName))
+      .split('{methodCamel}')
+      .join(lowerFirst(entry.methodName));
+}

package/src/react-query/index.ts

@@ -0,0 +1,40 @@
+import type {
+  QueryKey,
+  UseMutationOptions,
+  UseQueryOptions,
+} from '@tanstack/react-query';
+import { useMutation, useQuery } from '@tanstack/react-query';
+
+type UnaryFn<TReq, TRes> = (request: TReq) => Promise<TRes>;
+
+/**
+ * Thin React Query wrapper around a generated unary client method.
+ */
+export function useProtoQuery<TReq extends object, TRes>(
+  method: UnaryFn<TReq, TRes>,
+  request: TReq,
+  options?: Omit<
+    UseQueryOptions<TRes, Error, TRes, QueryKey>,
+    'queryKey' | 'queryFn'
+  > & { queryKey?: QueryKey }
+) {
+  const queryKey = options?.queryKey ?? ['proto', method.name, request];
+  return useQuery({
+    ...options,
+    queryKey,
+    queryFn: () => method(request),
+  });
+}
+
+/**
+ * Thin React Query mutation wrapper around a generated unary client method.
+ */
+export function useProtoMutation<TReq extends object, TRes>(
+  method: UnaryFn<TReq, TRes>,
+  options?: UseMutationOptions<TRes, Error, TReq>
+) {
+  return useMutation({
+    ...options,
+    mutationFn: (request: TReq) => method(request),
+  });
+}