@markwasfy/loko-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loko contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @loko/react
+
+React bindings for [`loko`](https://www.npmjs.com/package/loko) — offline storage + sync, with reactive hooks.
+
+```bash
+npm install loko @loko/react
+```
+
+```tsx
+import { SyncProvider, useCollection, useSyncStatus } from "@loko/react";
+import { createSync, indexedDBStorage, restAdapter } from "loko";
+
+const sync = createSync({
+  name: "myapp",
+  storage: indexedDBStorage(),
+  adapter: restAdapter({ url: "/api/sync" }),
+});
+
+function Todos() {
+  const { items, put, remove, loading } = useCollection<Todo>("todos");
+  const { status, sync: syncNow } = useSyncStatus();
+  if (loading) return <p>Loading…</p>;
+  return (
+    <>
+      <button onClick={() => syncNow()}>{status}</button>
+      {items.map((t) => (
+        <label key={t.id}>
+          <input type="checkbox" checked={t.done} onChange={() => put({ ...t, done: !t.done })} />
+          {t.text} <button onClick={() => remove(t.id)}>✕</button>
+        </label>
+      ))}
+    </>
+  );
+}
+
+export default function App() {
+  return (
+    <SyncProvider sync={sync}>
+      <Todos />
+    </SyncProvider>
+  );
+}
+```
+
+## Hooks
+
+- `useCollection<T>(name)` → `{ items, loading, put, remove }`
+- `useDocument<T>(name, id)` → `{ item, loading, put, remove }`
+- `useSyncStatus()` → `{ status, sync }`
+- `useSync()` → the `Sync` instance from context
+
+All hooks are built on `useSyncExternalStore` for correct concurrent-mode behavior and re-render on local, sync, and cross-tab changes.
+
+Requires React 18+. License: MIT.

package/dist/index.cjs

@@ -0,0 +1,76 @@
+'use strict';
+
+var react = require('react');
+
+// src/index.ts
+var SyncContext = react.createContext(null);
+function SyncProvider({ sync, children }) {
+  return react.createElement(SyncContext.Provider, { value: sync }, children);
+}
+function useSync() {
+  const sync = react.useContext(SyncContext);
+  if (!sync) {
+    throw new Error("useSync(): no <SyncProvider> found in the component tree.");
+  }
+  return sync;
+}
+function useCollection(name) {
+  const sync = useSync();
+  const collection = react.useMemo(() => sync.collection(name), [sync, name]);
+  const snapshot = react.useRef({ items: [], loading: true });
+  const subscribe = react.useCallback(
+    (onStoreChange) => collection.subscribe((items2) => {
+      snapshot.current = { items: items2, loading: false };
+      onStoreChange();
+    }),
+    [collection]
+  );
+  const getSnapshot = react.useCallback(() => snapshot.current, []);
+  const { items, loading } = react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const put = react.useCallback((record) => collection.put(record), [collection]);
+  const remove = react.useCallback((id) => collection.delete(id), [collection]);
+  return { items, loading, put, remove };
+}
+function useDocument(name, id) {
+  const sync = useSync();
+  const collection = react.useMemo(() => sync.collection(name), [sync, name]);
+  const snapshot = react.useRef({
+    item: void 0,
+    loading: true
+  });
+  const subscribe = react.useCallback(
+    (onStoreChange) => collection.subscribeOne(id, (item2) => {
+      snapshot.current = { item: item2, loading: false };
+      onStoreChange();
+    }),
+    [collection, id]
+  );
+  const getSnapshot = react.useCallback(() => snapshot.current, []);
+  const { item, loading } = react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const put = react.useCallback((record) => collection.put(record), [collection]);
+  const remove = react.useCallback(() => collection.delete(id), [collection, id]);
+  return { item, loading, put, remove };
+}
+function useSyncStatus() {
+  const sync = useSync();
+  const status = react.useRef(sync.status);
+  const subscribe = react.useCallback(
+    (onStoreChange) => sync.on("status", ({ status: s }) => {
+      status.current = s;
+      onStoreChange();
+    }),
+    [sync]
+  );
+  const getSnapshot = react.useCallback(() => status.current, []);
+  const current = react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const trigger = react.useCallback(() => sync.sync(), [sync]);
+  return { status: current, sync: trigger };
+}
+
+exports.SyncProvider = SyncProvider;
+exports.useCollection = useCollection;
+exports.useDocument = useDocument;
+exports.useSync = useSync;
+exports.useSyncStatus = useSyncStatus;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["createContext","createElement","useContext","useMemo","useRef","useCallback","items","useSyncExternalStore","item"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Sync, SyncStatus } from \"@markwasfy/loko\";\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type ReactNode,\n} from \"react\";\n\nconst SyncContext = createContext<Sync | null>(null);\n\nexport interface SyncProviderProps {\n  sync: Sync;\n  children?: ReactNode;\n}\n\n/** Provides a {@link Sync} instance to descendant hooks. */\nexport function SyncProvider({ sync, children }: SyncProviderProps): ReactNode {\n  return createElement(SyncContext.Provider, { value: sync }, children);\n}\n\n/** Access the Sync instance from context. Throws if no provider is mounted. */\nexport function useSync(): Sync {\n  const sync = useContext(SyncContext);\n  if (!sync) {\n    throw new Error(\"useSync(): no <SyncProvider> found in the component tree.\");\n  }\n  return sync;\n}\n\nexport interface UseCollectionResult<T> {\n  items: T[];\n  loading: boolean;\n  put: (record: T) => Promise<T>;\n  remove: (id: string) => Promise<void>;\n}\n\n/**\n * Subscribe a component to a collection. Re-renders on any change (local,\n * sync, or another tab). Built on `useSyncExternalStore`.\n */\nexport function useCollection<T extends Record<string, unknown> = Record<string, unknown>>(\n  name: string,\n): UseCollectionResult<T> {\n  const sync = useSync();\n  const collection = useMemo(() => sync.collection<T>(name), [sync, name]);\n\n  // Cache the snapshot as a stable object that changes on every emission so\n  // useSyncExternalStore doesn't bail out (e.g. when an empty result repeats).\n  const snapshot = useRef<{ items: T[]; loading: boolean }>({ items: [], loading: true });\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      collection.subscribe((items) => {\n        snapshot.current = { items, loading: false };\n        onStoreChange();\n      }),\n    [collection],\n  );\n\n  const getSnapshot = useCallback(() => snapshot.current, []);\n  const { items, loading } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const put = useCallback((record: T) => collection.put(record), [collection]);\n  const remove = useCallback((id: string) => collection.delete(id), [collection]);\n\n  return { items, loading, put, remove };\n}\n\nexport interface UseDocumentResult<T> {\n  item: T | undefined;\n  loading: boolean;\n  put: (record: T) => Promise<T>;\n  remove: () => Promise<void>;\n}\n\n/** Subscribe a component to a single record by id. */\nexport function useDocument<T extends Record<string, unknown> = Record<string, unknown>>(\n  name: string,\n  id: string,\n): UseDocumentResult<T> {\n  const sync = useSync();\n  const collection = useMemo(() => sync.collection<T>(name), [sync, name]);\n\n  const snapshot = useRef<{ item: T | undefined; loading: boolean }>({\n    item: undefined,\n    loading: true,\n  });\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      collection.subscribeOne(id, (item) => {\n        snapshot.current = { item, loading: false };\n        onStoreChange();\n      }),\n    [collection, id],\n  );\n\n  const getSnapshot = useCallback(() => snapshot.current, []);\n  const { item, loading } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const put = useCallback((record: T) => collection.put(record), [collection]);\n  const remove = useCallback(() => collection.delete(id), [collection, id]);\n\n  return { item, loading, put, remove };\n}\n\nexport interface UseSyncStatusResult {\n  status: SyncStatus;\n  sync: () => Promise<{ pushed: number; pulled: number }>;\n}\n\n/** Track sync status reactively and expose a manual trigger. */\nexport function useSyncStatus(): UseSyncStatusResult {\n  const sync = useSync();\n  const status = useRef<SyncStatus>(sync.status);\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      sync.on(\"status\", ({ status: s }) => {\n        status.current = s;\n        onStoreChange();\n      }),\n    [sync],\n  );\n\n  const getSnapshot = useCallback(() => status.current, []);\n  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const trigger = useCallback(() => sync.sync(), [sync]);\n  return { status: current, sync: trigger };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,41 @@
+import { Sync, SyncStatus } from '@markwasfy/loko';
+import { ReactNode } from 'react';
+
+interface SyncProviderProps {
+    sync: Sync;
+    children?: ReactNode;
+}
+/** Provides a {@link Sync} instance to descendant hooks. */
+declare function SyncProvider({ sync, children }: SyncProviderProps): ReactNode;
+/** Access the Sync instance from context. Throws if no provider is mounted. */
+declare function useSync(): Sync;
+interface UseCollectionResult<T> {
+    items: T[];
+    loading: boolean;
+    put: (record: T) => Promise<T>;
+    remove: (id: string) => Promise<void>;
+}
+/**
+ * Subscribe a component to a collection. Re-renders on any change (local,
+ * sync, or another tab). Built on `useSyncExternalStore`.
+ */
+declare function useCollection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): UseCollectionResult<T>;
+interface UseDocumentResult<T> {
+    item: T | undefined;
+    loading: boolean;
+    put: (record: T) => Promise<T>;
+    remove: () => Promise<void>;
+}
+/** Subscribe a component to a single record by id. */
+declare function useDocument<T extends Record<string, unknown> = Record<string, unknown>>(name: string, id: string): UseDocumentResult<T>;
+interface UseSyncStatusResult {
+    status: SyncStatus;
+    sync: () => Promise<{
+        pushed: number;
+        pulled: number;
+    }>;
+}
+/** Track sync status reactively and expose a manual trigger. */
+declare function useSyncStatus(): UseSyncStatusResult;
+
+export { SyncProvider, type SyncProviderProps, type UseCollectionResult, type UseDocumentResult, type UseSyncStatusResult, useCollection, useDocument, useSync, useSyncStatus };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Sync, SyncStatus } from '@markwasfy/loko';
+import { ReactNode } from 'react';
+
+interface SyncProviderProps {
+    sync: Sync;
+    children?: ReactNode;
+}
+/** Provides a {@link Sync} instance to descendant hooks. */
+declare function SyncProvider({ sync, children }: SyncProviderProps): ReactNode;
+/** Access the Sync instance from context. Throws if no provider is mounted. */
+declare function useSync(): Sync;
+interface UseCollectionResult<T> {
+    items: T[];
+    loading: boolean;
+    put: (record: T) => Promise<T>;
+    remove: (id: string) => Promise<void>;
+}
+/**
+ * Subscribe a component to a collection. Re-renders on any change (local,
+ * sync, or another tab). Built on `useSyncExternalStore`.
+ */
+declare function useCollection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): UseCollectionResult<T>;
+interface UseDocumentResult<T> {
+    item: T | undefined;
+    loading: boolean;
+    put: (record: T) => Promise<T>;
+    remove: () => Promise<void>;
+}
+/** Subscribe a component to a single record by id. */
+declare function useDocument<T extends Record<string, unknown> = Record<string, unknown>>(name: string, id: string): UseDocumentResult<T>;
+interface UseSyncStatusResult {
+    status: SyncStatus;
+    sync: () => Promise<{
+        pushed: number;
+        pulled: number;
+    }>;
+}
+/** Track sync status reactively and expose a manual trigger. */
+declare function useSyncStatus(): UseSyncStatusResult;
+
+export { SyncProvider, type SyncProviderProps, type UseCollectionResult, type UseDocumentResult, type UseSyncStatusResult, useCollection, useDocument, useSync, useSyncStatus };

package/dist/index.js

@@ -0,0 +1,70 @@
+import { createContext, createElement, useContext, useMemo, useRef, useCallback, useSyncExternalStore } from 'react';
+
+// src/index.ts
+var SyncContext = createContext(null);
+function SyncProvider({ sync, children }) {
+  return createElement(SyncContext.Provider, { value: sync }, children);
+}
+function useSync() {
+  const sync = useContext(SyncContext);
+  if (!sync) {
+    throw new Error("useSync(): no <SyncProvider> found in the component tree.");
+  }
+  return sync;
+}
+function useCollection(name) {
+  const sync = useSync();
+  const collection = useMemo(() => sync.collection(name), [sync, name]);
+  const snapshot = useRef({ items: [], loading: true });
+  const subscribe = useCallback(
+    (onStoreChange) => collection.subscribe((items2) => {
+      snapshot.current = { items: items2, loading: false };
+      onStoreChange();
+    }),
+    [collection]
+  );
+  const getSnapshot = useCallback(() => snapshot.current, []);
+  const { items, loading } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const put = useCallback((record) => collection.put(record), [collection]);
+  const remove = useCallback((id) => collection.delete(id), [collection]);
+  return { items, loading, put, remove };
+}
+function useDocument(name, id) {
+  const sync = useSync();
+  const collection = useMemo(() => sync.collection(name), [sync, name]);
+  const snapshot = useRef({
+    item: void 0,
+    loading: true
+  });
+  const subscribe = useCallback(
+    (onStoreChange) => collection.subscribeOne(id, (item2) => {
+      snapshot.current = { item: item2, loading: false };
+      onStoreChange();
+    }),
+    [collection, id]
+  );
+  const getSnapshot = useCallback(() => snapshot.current, []);
+  const { item, loading } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const put = useCallback((record) => collection.put(record), [collection]);
+  const remove = useCallback(() => collection.delete(id), [collection, id]);
+  return { item, loading, put, remove };
+}
+function useSyncStatus() {
+  const sync = useSync();
+  const status = useRef(sync.status);
+  const subscribe = useCallback(
+    (onStoreChange) => sync.on("status", ({ status: s }) => {
+      status.current = s;
+      onStoreChange();
+    }),
+    [sync]
+  );
+  const getSnapshot = useCallback(() => status.current, []);
+  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const trigger = useCallback(() => sync.sync(), [sync]);
+  return { status: current, sync: trigger };
+}
+
+export { SyncProvider, useCollection, useDocument, useSync, useSyncStatus };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["items","item"],"mappings":"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","file":"index.js","sourcesContent":["import type { Sync, SyncStatus } from \"@markwasfy/loko\";\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type ReactNode,\n} from \"react\";\n\nconst SyncContext = createContext<Sync | null>(null);\n\nexport interface SyncProviderProps {\n  sync: Sync;\n  children?: ReactNode;\n}\n\n/** Provides a {@link Sync} instance to descendant hooks. */\nexport function SyncProvider({ sync, children }: SyncProviderProps): ReactNode {\n  return createElement(SyncContext.Provider, { value: sync }, children);\n}\n\n/** Access the Sync instance from context. Throws if no provider is mounted. */\nexport function useSync(): Sync {\n  const sync = useContext(SyncContext);\n  if (!sync) {\n    throw new Error(\"useSync(): no <SyncProvider> found in the component tree.\");\n  }\n  return sync;\n}\n\nexport interface UseCollectionResult<T> {\n  items: T[];\n  loading: boolean;\n  put: (record: T) => Promise<T>;\n  remove: (id: string) => Promise<void>;\n}\n\n/**\n * Subscribe a component to a collection. Re-renders on any change (local,\n * sync, or another tab). Built on `useSyncExternalStore`.\n */\nexport function useCollection<T extends Record<string, unknown> = Record<string, unknown>>(\n  name: string,\n): UseCollectionResult<T> {\n  const sync = useSync();\n  const collection = useMemo(() => sync.collection<T>(name), [sync, name]);\n\n  // Cache the snapshot as a stable object that changes on every emission so\n  // useSyncExternalStore doesn't bail out (e.g. when an empty result repeats).\n  const snapshot = useRef<{ items: T[]; loading: boolean }>({ items: [], loading: true });\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      collection.subscribe((items) => {\n        snapshot.current = { items, loading: false };\n        onStoreChange();\n      }),\n    [collection],\n  );\n\n  const getSnapshot = useCallback(() => snapshot.current, []);\n  const { items, loading } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const put = useCallback((record: T) => collection.put(record), [collection]);\n  const remove = useCallback((id: string) => collection.delete(id), [collection]);\n\n  return { items, loading, put, remove };\n}\n\nexport interface UseDocumentResult<T> {\n  item: T | undefined;\n  loading: boolean;\n  put: (record: T) => Promise<T>;\n  remove: () => Promise<void>;\n}\n\n/** Subscribe a component to a single record by id. */\nexport function useDocument<T extends Record<string, unknown> = Record<string, unknown>>(\n  name: string,\n  id: string,\n): UseDocumentResult<T> {\n  const sync = useSync();\n  const collection = useMemo(() => sync.collection<T>(name), [sync, name]);\n\n  const snapshot = useRef<{ item: T | undefined; loading: boolean }>({\n    item: undefined,\n    loading: true,\n  });\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      collection.subscribeOne(id, (item) => {\n        snapshot.current = { item, loading: false };\n        onStoreChange();\n      }),\n    [collection, id],\n  );\n\n  const getSnapshot = useCallback(() => snapshot.current, []);\n  const { item, loading } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const put = useCallback((record: T) => collection.put(record), [collection]);\n  const remove = useCallback(() => collection.delete(id), [collection, id]);\n\n  return { item, loading, put, remove };\n}\n\nexport interface UseSyncStatusResult {\n  status: SyncStatus;\n  sync: () => Promise<{ pushed: number; pulled: number }>;\n}\n\n/** Track sync status reactively and expose a manual trigger. */\nexport function useSyncStatus(): UseSyncStatusResult {\n  const sync = useSync();\n  const status = useRef<SyncStatus>(sync.status);\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      sync.on(\"status\", ({ status: s }) => {\n        status.current = s;\n        onStoreChange();\n      }),\n    [sync],\n  );\n\n  const getSnapshot = useCallback(() => status.current, []);\n  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  const trigger = useCallback(() => sync.sync(), [sync]);\n  return { status: current, sync: trigger };\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@markwasfy/loko-react",
+  "version": "0.1.0",
+  "description": "React bindings for loko — offline storage + sync hooks (useCollection, useDocument, useSyncStatus).",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "loko",
+    "offline",
+    "sync",
+    "react",
+    "hooks",
+    "indexeddb",
+    "local-first"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarkWasfy00/loko.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/MarkWasfy00/loko#readme",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@markwasfy/loko": "^0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "@markwasfy/loko": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}