react-smart-query 1.0.0

package/docs/TESTING.md

@@ -0,0 +1,61 @@
+# Testing & Debugging with React Smart Query
+
+Testing offline-first normalized data layers can be tricky, but `react-smart-query` provides dedicated utilities to make it painless.
+
+## 1. Setting up the Test Environment
+
+When testing components that use `useSmartQuery` or `useInfiniteSmartQuery`, you should wrap them in the `SmartQueryTestProvider` rather than standard QueryClientProviders. This ensures the internal registry and normalization engines are securely isolated per test.
+
+### Installation
+Make sure you import from the designated `testing` entry point, ensuring test tools aren't bundled into production:
+```tsx
+import { render } from '@testing-library/react-native';
+import { SmartQueryTestProvider } from 'react-smart-query/testing';
+
+const renderWithProvider = (ui: React.ReactElement) => {
+  return render(
+    <SmartQueryTestProvider>
+      {ui}
+    </SmartQueryTestProvider>
+  );
+};
+```
+
+## 2. Seeding Data
+Oftentimes, you want to test how a component behaves *given* some pre-existing cached state, without mocking the network layer heavily. You can seed the cache directly inside your tests using the `seedCache` utility.
+
+```tsx
+import { SmartQueryTestProvider, seedCache } from 'react-smart-query/testing';
+
+beforeEach(() => {
+  seedCache(['expenses', 'user-123'], [
+    { id: '1', amount: 50, desc: 'Coffee' },
+    { id: '2', amount: 120, desc: 'Groceries' }
+  ]);
+});
+
+test('renders expenses from cache directly', () => {
+  const { getByText } = renderWithProvider(<ExpenseList userId="user-123" />);
+  expect(getByText('Coffee')).toBeTruthy();
+});
+```
+
+## 3. The Debugger
+If you ever find yourself wondering exactly what's sitting in the `react-smart-query` internal normalization maps, you can use the built in debugger. We highly recommend only tying this to `__DEV__`.
+
+### Activating the Debugger
+In your root file (like App.tsx):
+```tsx
+if (__DEV__) {
+  require('react-smart-query/debug');
+}
+```
+
+### Retrieving Snapshots
+Once activated, you can trigger snapshots to the console representing the current entire data map and state.
+```tsx
+import { smartQueryDebug } from 'react-smart-query';
+
+// From a component effect, or attached to a dev-only button:
+await smartQueryDebug.snapshot();
+```

package/package.json

@@ -0,0 +1,136 @@
+{
+  "name": "react-smart-query",
+  "version": "1.0.0",
+  "description": "Offline-first, normalized, cache-versioned data layer for React Native and Expo. Built on TanStack Query with MMKV (native) and IndexedDB (web).",
+  "author": "Subham Ghosh <subham49ghosh@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/subham067/react-smart-query.git"
+  },
+  "homepage": "https://github.com/subham067/react-smart-query#readme",
+  "keywords": [
+    "react-native",
+    "expo",
+    "offline-first",
+    "cache",
+    "tanstack-query",
+    "react-query",
+    "mmkv",
+    "indexeddb",
+    "normalized",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.mjs",
+      "require": "./dist/testing.js"
+    },
+    "./debug": {
+      "types": "./dist/utils/debug.d.ts",
+      "import": "./dist/utils/debug.mjs",
+      "require": "./dist/utils/debug.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/utils/debug.js",
+    "./dist/utils/debug.mjs"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/testing.ts src/utils/debug.ts --format cjs,esm --dts --clean",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "fast-deep-equal": ">=3.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-mmkv": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-mmkv": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.96.2",
+    "@testing-library/react-native": "^12.0.0",
+    "@types/jest": "^29.0.0",
+    "@types/react": "^18.3.28",
+    "@types/react-native": "^0.72.8",
+    "fast-deep-equal": "^3.1.3",
+    "jest": "^29.0.0",
+    "jest-expo": "^50.0.0",
+    "react": "^19.2.4",
+    "react-native": ">=0.72.0",
+    "react-native-mmkv": "^4.3.0",
+    "babel-jest": "^29.0.0",
+    "babel-preset-expo": "~54.0.0",
+    "ts-jest": "^29.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "jest": {
+    "preset": "react-native",
+    "transform": {
+      "^.+\\.[jt]sx?$": "babel-jest"
+    },
+    "transformIgnorePatterns": [
+      "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@unimodules/.*|unimodules|sentry-expo|native-base|react-native-svg)"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.test.[jt]s?(x)"
+    ],
+    "setupFilesAfterEnv": [
+      "@testing-library/react-native/extend-expect"
+    ],
+    "moduleNameMapper": {
+      "^react-native-mmkv$": "<rootDir>/__mocks__/react-native-mmkv.ts"
+    }
+  },
+  "tsup": {
+    "entry": [
+      "src/index.ts",
+      "src/testing.ts",
+      "src/utils/debug.ts"
+    ],
+    "format": [
+      "cjs",
+      "esm"
+    ],
+    "dts": true,
+    "clean": true,
+    "sourcemap": true,
+    "treeshake": true,
+    "external": [
+      "react",
+      "react-native",
+      "@tanstack/react-query",
+      "react-native-mmkv",
+      "fast-deep-equal"
+    ]
+  }
+}