@pylonsync/react-native 0.3.53

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pylonsync/react-native",
+  "publishConfig": {
+  "access": "public"
+},
+"version": "0.3.53",
+"type": "module",
+"main": "src/index.ts",
+"types": "src/index.ts",
+"scripts": {
+  "build": "tsc -p tsconfig.json --noEmit",
+  "check": "tsc -p tsconfig.json --noEmit"
+},
+"dependencies": {
+  "@pylonsync/react": "0.3.53",
+  "@pylonsync/sdk": "0.3.53",
+  "@pylonsync/sync": "0.3.53"
+},
+"peerDependencies": {
+  "react": ">=19",
+  "react-native": ">=0.74",
+  "@react-native-async-storage/async-storage": ">=1.19",
+  "@react-native-community/netinfo": ">=9.0"
+},
+"devDependencies": {
+  "@types/react": "^19.0.0"
+}
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// @pylonsync/react-native
+//
+// Thin layer on top of @pylonsync/react. The hooks, db, useRoom, useSession
+// are all the React versions — RN has React + fetch + WebSocket and shares
+// the rendering layer, so the entire React API works as-is. This package
+// adds:
+//
+//   - `init()` that bootstraps an AsyncStorage-backed Storage adapter so
+//     the sync engine and React free helpers persist tokens / client_id
+//     across cold launches
+//   - `useNetworkStatus` — RN-specific NetInfo subscription
+//   - `AsyncStoragePersistence` / `OfflineStore` — optional manual cache
+//     for apps that want a separate offline layer
+//
+// Why no parallel hook implementations? The previous RN hooks were a
+// stripped-down copy that lost `useSession`, `useShard`, `useInfiniteQuery`,
+// `usePaginatedQuery`, `where` / `orderBy` / `include`. Re-exporting from
+// React keeps the two surfaces in lockstep.
+// ---------------------------------------------------------------------------
+
+import {
+  init as reactInit,
+  setReactStorage,
+} from "@pylonsync/react";
+import type { SyncEngineConfig } from "@pylonsync/sync";
+import { createAsyncStorageBridge } from "./storage";
+
+// All hooks, db, callFn, configureClient, etc.
+export * from "@pylonsync/react";
+
+// React Native specific.
+export { useNetworkStatus } from "./useNetworkStatus";
+export type { NetworkStatus } from "./useNetworkStatus";
+export {
+  AsyncStoragePersistence,
+  OfflineStore,
+  createAsyncStorageBridge,
+  type PersistenceAdapter,
+} from "./storage";
+
+/**
+ * Initialize Pylon for a React Native app. Reads the persisted token /
+ * client_id from AsyncStorage, registers the bridge with both the sync
+ * engine and the React free helpers, then starts sync.
+ *
+ * Returns a Promise so RN apps can `await init(...)` before rendering —
+ * otherwise the first paint would render against an unauthenticated cache.
+ *
+ * ```tsx
+ * await init({ baseUrl: "https://api.example.com" });
+ * AppRegistry.registerComponent("App", () => RootApp);
+ * ```
+ */
+export async function init(
+  config?: Partial<SyncEngineConfig> & { baseUrl?: string },
+): Promise<void> {
+  const storage = await createAsyncStorageBridge();
+  setReactStorage(storage);
+  reactInit({ ...config, storage });
+}

package/src/storage.ts

@@ -0,0 +1,145 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import {
+  createWriteThroughStorage,
+  type Storage as PylonStorage,
+} from "@pylonsync/sync";
+
+// ---------------------------------------------------------------------------
+// Sync key-value adapter (AsyncStorage-backed)
+//
+// Pylon's sync engine uses a *synchronous* Storage interface for hot-path
+// state (auth token, client_id) — async would force the engine to be
+// async-all-the-way-down. AsyncStorage is async. The bridge: read seeds
+// into memory once at startup, then write through to AsyncStorage in the
+// background. Reads are immediate, writes are eventually-consistent.
+// ---------------------------------------------------------------------------
+
+/**
+ * Hot-path keys we eagerly read into memory at boot. Anything outside this
+ * set is missed until the engine writes to it (which then immediately
+ * mirrors to AsyncStorage). Add to this list if a new sync-engine-internal
+ * key shows up.
+ */
+const HOT_KEYS = [
+  "pylon:client_id",
+  "pylon_token",
+  // Wildcards aren't supported here; namespace-aware pylon apps register
+  // keys via `init({ appName })` before the first request, which prefixes
+  // tokens as `pylon:<app>:token`. The seed loader scans for matches.
+];
+
+/**
+ * Build a sync-engine-compatible Storage adapter on top of AsyncStorage.
+ * Reads return immediately from an in-memory cache seeded from AsyncStorage.
+ * Writes update the cache and fire-and-forget the AsyncStorage write.
+ *
+ * Call before `init()` so the SyncEngine constructor can read the cached
+ * client_id / token without a Promise hop.
+ */
+export async function createAsyncStorageBridge(): Promise<PylonStorage> {
+  // Pull in any existing pylon keys so a cold launch re-uses the same
+  // client_id (so the server's per-client diagnostics line up across
+  // sessions) and the same token (so the user stays signed in).
+  const allKeys = await AsyncStorage.getAllKeys();
+  const pylonKeys = allKeys.filter(
+    (k) => k.startsWith("pylon_") || k.startsWith("pylon:"),
+  );
+  const merged = [...new Set([...HOT_KEYS, ...pylonKeys])];
+  const seed: Record<string, string> = {};
+  if (merged.length > 0) {
+    const values = await Promise.all(merged.map((k) => AsyncStorage.getItem(k)));
+    for (let i = 0; i < merged.length; i++) {
+      const v = values[i];
+      if (v != null) seed[merged[i]] = v;
+    }
+  }
+  return createWriteThroughStorage(seed, (key, value) => {
+    if (value === null) {
+      void AsyncStorage.removeItem(key);
+    } else {
+      void AsyncStorage.setItem(key, value);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Optional higher-level offline-row store
+//
+// Kept for apps that want a separate manual cache (e.g. offline mutation
+// queue persistence outside the sync engine's IndexedDB equivalent).
+// SyncEngine handles the common case automatically once given a Storage.
+// ---------------------------------------------------------------------------
+
+export interface PersistenceAdapter {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+export class AsyncStoragePersistence implements PersistenceAdapter {
+  private prefix: string;
+
+  constructor(prefix = "pylon") {
+    this.prefix = prefix;
+  }
+
+  private prefixedKey(key: string): string {
+    return `${this.prefix}:${key}`;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return AsyncStorage.getItem(this.prefixedKey(key));
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await AsyncStorage.setItem(this.prefixedKey(key), value);
+  }
+
+  async remove(key: string): Promise<void> {
+    await AsyncStorage.removeItem(this.prefixedKey(key));
+  }
+
+  async keys(): Promise<string[]> {
+    const allKeys = await AsyncStorage.getAllKeys();
+    const prefixWithSep = `${this.prefix}:`;
+    return allKeys
+      .filter((k) => k.startsWith(prefixWithSep))
+      .map((k) => k.slice(prefixWithSep.length));
+  }
+}
+
+export class OfflineStore {
+  private adapter: PersistenceAdapter;
+
+  constructor(adapter?: PersistenceAdapter) {
+    this.adapter = adapter ?? new AsyncStoragePersistence();
+  }
+
+  async saveEntities(
+    entity: string,
+    rows: Record<string, unknown>[],
+  ): Promise<void> {
+    await this.adapter.set(`entities:${entity}`, JSON.stringify(rows));
+  }
+
+  async loadEntities(
+    entity: string,
+  ): Promise<Record<string, unknown>[]> {
+    const data = await this.adapter.get(`entities:${entity}`);
+    return data ? (JSON.parse(data) as Record<string, unknown>[]) : [];
+  }
+
+  async saveCursor(cursor: string): Promise<void> {
+    await this.adapter.set("sync:cursor", cursor);
+  }
+
+  async loadCursor(): Promise<string | null> {
+    return this.adapter.get("sync:cursor");
+  }
+
+  async clear(): Promise<void> {
+    const keys = await this.adapter.keys();
+    await Promise.all(keys.map((key) => this.adapter.remove(key)));
+  }
+}

package/src/useNetworkStatus.ts

@@ -0,0 +1,41 @@
+import { useState, useEffect } from "react";
+import NetInfo, { type NetInfoState } from "@react-native-community/netinfo";
+
+// ---------------------------------------------------------------------------
+// Network status hook
+// ---------------------------------------------------------------------------
+
+export interface NetworkStatus {
+  /** Whether the device currently has internet connectivity. */
+  isOnline: boolean;
+  /** Connection type reported by NetInfo (e.g. "wifi", "cellular", "none"). */
+  connectionType: string;
+}
+
+/**
+ * Subscribe to network connectivity changes. Useful for toggling offline
+ * banners or pausing sync when the device goes offline.
+ *
+ * ```tsx
+ * const { isOnline, connectionType } = useNetworkStatus();
+ * if (!isOnline) return <OfflineBanner />;
+ * ```
+ */
+export function useNetworkStatus(): NetworkStatus {
+  const [isOnline, setIsOnline] = useState(true);
+  const [connectionType, setConnectionType] = useState<string>("unknown");
+
+  useEffect(() => {
+    const handleChange = (state: NetInfoState) => {
+      setIsOnline(state.isConnected ?? false);
+      setConnectionType(state.type);
+    };
+
+    const unsubscribe = NetInfo.addEventListener(handleChange);
+    return () => {
+      unsubscribe();
+    };
+  }, []);
+
+  return { isOnline, connectionType };
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src"
+  ]
+}
+