@vishalsharma7nov/react-native-proto 0.2.2

package/lib/module/native-grpc/index.js

@@ -0,0 +1,233 @@
+"use strict";
+
+import { ProtoClientError } from '../errors';
+function getGlobalBuffer() {
+  const candidate = globalThis.Buffer;
+  return typeof candidate?.from === 'function' ? candidate : undefined;
+}
+
+/** Encode bytes to base64 without requiring a Buffer polyfill on RN. */
+export function bytesToBase64(bytes) {
+  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) {
+  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() {
+  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');
+    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) {
+  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() {
+  const mod = getNativeModule();
+  if (!mod) {
+    return false;
+  }
+  globalThis.__REACT_NATIVE_PROTO_NATIVE_GRPC__ = createBridgeFromNativeModule(mod);
+  return true;
+}
+function getBridge() {
+  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, rpcPath) {
+  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, codecs, input) {
+  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;
+  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;
+  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, codecs, input) {
+  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() {
+  if (typeof globalThis.__REACT_NATIVE_PROTO_NATIVE_GRPC__?.unary === 'function') {
+    return true;
+  }
+  return getNativeModule() != null;
+}
+//# sourceMappingURL=index.js.map

package/lib/module/native-grpc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ProtoClientError","getGlobalBuffer","candidate","globalThis","Buffer","from","undefined","bytesToBase64","bytes","BufferCtor","toString","binary","i","length","String","fromCharCode","btoa","Error","base64ToBytes","base64","buf","Uint8Array","buffer","byteOffset","byteLength","atob","out","charCodeAt","getNativeModule","rn","require","mod","NativeModules","ReactNativeProtoNativeGrpc","unary","createBridgeFromNativeModule","baseUrl","rpcPath","requestBytes","headers","timeoutMs","responseBase64","JSON","stringify","installNativeGrpcBridgeFromNativeModule","__REACT_NATIVE_PROTO_NATIVE_GRPC__","getBridge","existing","installed","code","message","headersFromConfig","config","getHeaders","cause","nativeGrpcUnary","codecs","input","bridge","entry","request","requestCodec","get","requestType","responseCodec","responseType","encode","responseBytes","retryable","maxResponseBytes","decode","nativeGrpcStream","stream","frames","frame","onMessage","isNativeGrpcAvailable"],"sourceRoot":"../../../src","sources":["native-grpc/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/offline-queue.js

@@ -0,0 +1,132 @@
+"use strict";
+
+import { ProtoClientError } from './errors';
+/**
+ * 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 {
+  items = [];
+  online = true;
+  flushing = false;
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 50;
+    this.onChange = options.onChange;
+    this.storage = options.storage;
+  }
+  async hydrate() {
+    if (!this.storage) return;
+    const loaded = await this.storage.load();
+    this.items = Array.isArray(loaded) ? loaded.slice(0, this.maxSize) : [];
+    this.emit();
+  }
+  setOnline(online) {
+    this.online = online;
+    if (online) {
+      void this.flush();
+    }
+  }
+  isOnline() {
+    return this.online;
+  }
+  size() {
+    return this.items.length;
+  }
+
+  /**
+   * Run immediately when online; otherwise enqueue and resolve after flush.
+   */
+  async runOrEnqueue(label, run) {
+    if (this.online) {
+      return run();
+    }
+    return new Promise((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, run) {
+    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() {
+    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() {
+    this.items = [];
+    this.emit();
+    void this.persist();
+  }
+  emit() {
+    if (this.onChange) {
+      this.onChange(this.items.length);
+    }
+  }
+  async persist() {
+    if (!this.storage) return;
+    await this.storage.save(this.items);
+  }
+}
+//# sourceMappingURL=offline-queue.js.map

package/lib/module/offline-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ProtoClientError","OfflineMutationQueue","items","online","flushing","constructor","options","maxSize","onChange","storage","hydrate","loaded","load","Array","isArray","slice","emit","setOnline","flush","isOnline","size","length","runOrEnqueue","label","run","Promise","resolve","reject","code","message","id","Date","now","Math","random","toString","push","enqueuedAt","result","persist","enqueue","ok","failed","item","shift","clear","save"],"sourceRoot":"../../src","sources":["offline-queue.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/module/path-templates.js

@@ -0,0 +1,39 @@
+"use strict";
+
+function packagePrefix(entry) {
+  return entry.packageName ? `${entry.packageName}.` : '';
+}
+function lowerFirst(value) {
+  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 = 'connect') {
+  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) {
+  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));
+}
+//# sourceMappingURL=path-templates.js.map

package/lib/module/path-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["packagePrefix","entry","packageName","lowerFirst","value","charAt","toLowerCase","slice","createPathForMethod","preset","serviceName","methodName","pathFromTemplate","template","split","join","rpcPath"],"sourceRoot":"../../src","sources":["path-templates.ts"],"mappings":";;AASA,SAASA,aAAaA,CAACC,KAAqB,EAAU;EACpD,OAAOA,KAAK,CAACC,WAAW,GAAG,GAAGD,KAAK,CAACC,WAAW,GAAG,GAAG,EAAE;AACzD;AAEA,SAASC,UAAUA,CAACC,KAAa,EAAU;EACzC,IAAI,CAACA,KAAK,EAAE,OAAOA,KAAK;EACxB,OAAOA,KAAK,CAACC,MAAM,CAAC,CAAC,CAAC,CAACC,WAAW,CAAC,CAAC,GAAGF,KAAK,CAACG,KAAK,CAAC,CAAC,CAAC;AACvD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,mBAAmBA,CACjCC,MAA0B,GAAG,SAAS,EACH;EACnC,QAAQA,MAAM;IACZ,KAAK,SAAS;MACZ,OAAQR,KAAK,IACX,OAAOE,UAAU,CAACF,KAAK,CAACS,WAAW,CAAC,IAAIP,UAAU,CAACF,KAAK,CAACU,UAAU,CAAC,EAAE;IAC1E,KAAK,cAAc;IACnB,KAAK,SAAS;IACd,KAAK,UAAU;IACf,KAAK,OAAO;IACZ;MACE,OAAQV,KAAK,IACX,IAAID,aAAa,CAACC,KAAK,CAAC,GAAGA,KAAK,CAACS,WAAW,IAAIT,KAAK,CAACU,UAAU,EAAE;EACxE;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAC9BC,QAAgB,EACmB;EACnC,OAAQZ,KAAK,IACXY,QAAQ,CACLC,KAAK,CAAC,WAAW,CAAC,CAClBC,IAAI,CAACd,KAAK,CAACC,WAAW,CAAC,CACvBY,KAAK,CAAC,WAAW,CAAC,CAClBC,IAAI,CAACd,KAAK,CAACS,WAAW,CAAC,CACvBI,KAAK,CAAC,UAAU,CAAC,CACjBC,IAAI,CAACd,KAAK,CAACU,UAAU,CAAC,CACtBG,KAAK,CAAC,WAAW,CAAC,CAClBC,IAAI,CAACd,KAAK,CAACe,OAAO,CAAC,CACnBF,KAAK,CAAC,gBAAgB,CAAC,CACvBC,IAAI,CAACZ,UAAU,CAACF,KAAK,CAACS,WAAW,CAAC,CAAC,CACnCI,KAAK,CAAC,eAAe,CAAC,CACtBC,IAAI,CAACZ,UAAU,CAACF,KAAK,CAACU,UAAU,CAAC,CAAC;AACzC","ignoreList":[]}

package/lib/module/react-query/index.js

@@ -0,0 +1,25 @@
+"use strict";
+
+import { useMutation, useQuery } from '@tanstack/react-query';
+/**
+ * Thin React Query wrapper around a generated unary client method.
+ */
+export function useProtoQuery(method, request, options) {
+  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(method, options) {
+  return useMutation({
+    ...options,
+    mutationFn: request => method(request)
+  });
+}
+//# sourceMappingURL=index.js.map

package/lib/module/react-query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useMutation","useQuery","useProtoQuery","method","request","options","queryKey","name","queryFn","useProtoMutation","mutationFn"],"sourceRoot":"../../../src","sources":["react-query/index.ts"],"mappings":";;AAKA,SAASA,WAAW,EAAEC,QAAQ,QAAQ,uBAAuB;AAI7D;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAC3BC,MAA2B,EAC3BC,OAAa,EACbC,OAG2B,EAC3B;EACA,MAAMC,QAAQ,GAAGD,OAAO,EAAEC,QAAQ,IAAI,CAAC,OAAO,EAAEH,MAAM,CAACI,IAAI,EAAEH,OAAO,CAAC;EACrE,OAAOH,QAAQ,CAAC;IACd,GAAGI,OAAO;IACVC,QAAQ;IACRE,OAAO,EAAEA,CAAA,KAAML,MAAM,CAACC,OAAO;EAC/B,CAAC,CAAC;AACJ;;AAEA;AACA;AACA;AACA,OAAO,SAASK,gBAAgBA,CAC9BN,MAA2B,EAC3BE,OAA+C,EAC/C;EACA,OAAOL,WAAW,CAAC;IACjB,GAAGK,OAAO;IACVK,UAAU,EAAGN,OAAa,IAAKD,MAAM,CAACC,OAAO;EAC/C,CAAC,CAAC;AACJ","ignoreList":[]}