@koolbase/react-native 12.3.0 → 12.5.0

package/dist/cjs/index.d.ts

@@ -18,3 +18,14 @@ export declare const Koolbase: {
     checkVersion(currentVersion: string): VersionCheckResult;
 };
 export { SecureAuthStorage } from './auth-storage.js';
+export type { UseCollectionResult } from './use-collection.js';
+/**
+ * A collection as React state: loading, loaded or error, with refresh and
+ * loadMore. Equality filters only for now: `where: { field: value }`.
+ * Use it after Koolbase.initialize() (in an exported app, inside KoolbaseRoot).
+ *
+ * ```tsx
+ * const songs = useCollection('songs', { where: { genre: 'jazz' }, orderBy: 'title' });
+ * ```
+ */
+export declare const useCollection: (collection: string, query?: import("@koolbase/core").CollectionQuery) => import("./use-collection.js").UseCollectionResult;

package/dist/cjs/index.js

@@ -20,12 +20,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SecureAuthStorage = exports.Koolbase = exports.reactNativePlatform = void 0;
+exports.useCollection = exports.SecureAuthStorage = exports.Koolbase = exports.reactNativePlatform = void 0;
 __exportStar(require("@koolbase/core"), exports);
 var platform_js_1 = require("./platform.js");
 Object.defineProperty(exports, "reactNativePlatform", { enumerable: true, get: function () { return platform_js_1.reactNativePlatform; } });
 const core_1 = require("@koolbase/core");
 const platform_js_2 = require("./platform.js");
+const use_collection_js_1 = require("./use-collection.js");
 let _auth = null;
 let _db = null;
 let _storage = null;
@@ -34,6 +35,8 @@ let _realtime = null;
 let _functions = null;
 let _flags = null;
 let _analytics = null;
+// While analytics is off, calls are harmless no-ops rather than a crash.
+const analyticsOff = (0, core_1.disabledAnalytics)();
 let _messaging = null;
 let _initialized = false;
 // The in-flight initialize, so overlapping callers await the same one.
@@ -75,7 +78,8 @@ exports.Koolbase = {
             const deviceId = await (0, core_1.getOrCreateDeviceId)();
             _flags = new core_1.KoolbaseFlags(config, deviceId);
             // Initialize analytics
-            if (config.analyticsEnabled !== false) {
+            // Opt-in: nothing is sent unless the app asks for it.
+            if (config.analyticsEnabled === true) {
                 _analytics = new core_1.KoolbaseAnalytics(config, () => _auth?.currentUser?.id ?? null);
                 await _analytics.init(config.appVersion);
             }
@@ -137,7 +141,7 @@ exports.Koolbase = {
     },
     get analytics() {
         ensureInitialized();
-        return _analytics;
+        return _analytics ?? analyticsOff;
     },
     get messaging() {
         ensureInitialized();
@@ -150,3 +154,13 @@ exports.Koolbase = {
 };
 var auth_storage_js_1 = require("./auth-storage.js");
 Object.defineProperty(exports, "SecureAuthStorage", { enumerable: true, get: function () { return auth_storage_js_1.SecureAuthStorage; } });
+/**
+ * A collection as React state: loading, loaded or error, with refresh and
+ * loadMore. Equality filters only for now: `where: { field: value }`.
+ * Use it after Koolbase.initialize() (in an exported app, inside KoolbaseRoot).
+ *
+ * ```tsx
+ * const songs = useCollection('songs', { where: { genre: 'jazz' }, orderBy: 'title' });
+ * ```
+ */
+exports.useCollection = (0, use_collection_js_1.createUseCollection)(() => exports.Koolbase.db);

package/dist/cjs/use-collection.d.ts

@@ -0,0 +1,12 @@
+import { type CollectionQuery, type CollectionState, type KoolbaseDatabase } from '@koolbase/core';
+export interface UseCollectionResult extends CollectionState {
+    /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+    /**
+     * The next page, appended, while hasMore. If rows are added or removed on
+     * the server between pages, one can be skipped until refresh(); none is
+     * ever shown twice.
+     */
+    loadMore: () => Promise<void>;
+}
+export declare function createUseCollection(getDb: () => Pick<KoolbaseDatabase, 'query'>): (collection: string, query?: CollectionQuery) => UseCollectionResult;

package/dist/cjs/use-collection.js

@@ -0,0 +1,39 @@
+"use strict";
+// useCollection: a Koolbase collection as React state.
+//
+// A thin wrapper. Everything about getting the records right lives in
+// @koolbase/core's KoolbaseCollectionController, which is tested there; this
+// file only ties one controller's lifetime to a component's.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUseCollection = createUseCollection;
+const react_1 = require("react");
+const core_1 = require("@koolbase/core");
+const noop = () => { };
+const done = () => Promise.resolve();
+function createUseCollection(getDb) {
+    return function useCollection(collection, query = {}) {
+        // The query as a value: an inline `where` object is a new object every
+        // render, and must not start a new fetch every render.
+        const key = (0, core_1.collectionQueryKey)(collection, query);
+        const [current, setCurrent] = (0, react_1.useState)(null);
+        (0, react_1.useEffect)(() => {
+            // Created here, not during render. Under React strict mode an effect
+            // runs, cleans up and runs again; each run gets its own controller, so
+            // the one left running is never one that was already disposed.
+            const controller = new core_1.KoolbaseCollectionController(getDb(), collection, query);
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+            // Depends on key alone: key is collection + query, as a value.
+        }, [key]);
+        // A controller from the previous key reads as a fresh load, never as
+        // the previous query's records.
+        const controller = current?.key === key ? current.controller : null;
+        const subscribe = (0, react_1.useCallback)((onChange) => (controller ? controller.subscribe(onChange) : noop), [controller]);
+        const getSnapshot = (0, react_1.useCallback)(() => (controller ? controller.getState() : core_1.initialCollectionState), [controller]);
+        const state = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+        const refresh = (0, react_1.useCallback)(() => (controller ? controller.refresh() : done()), [controller]);
+        const loadMore = (0, react_1.useCallback)(() => (controller ? controller.loadMore() : done()), [controller]);
+        return { ...state, refresh, loadMore };
+    };
+}

package/dist/esm/index.d.ts

@@ -18,3 +18,14 @@ export declare const Koolbase: {
     checkVersion(currentVersion: string): VersionCheckResult;
 };
 export { SecureAuthStorage } from './auth-storage.js';
+export type { UseCollectionResult } from './use-collection.js';
+/**
+ * A collection as React state: loading, loaded or error, with refresh and
+ * loadMore. Equality filters only for now: `where: { field: value }`.
+ * Use it after Koolbase.initialize() (in an exported app, inside KoolbaseRoot).
+ *
+ * ```tsx
+ * const songs = useCollection('songs', { where: { genre: 'jazz' }, orderBy: 'title' });
+ * ```
+ */
+export declare const useCollection: (collection: string, query?: import("@koolbase/core").CollectionQuery) => import("./use-collection.js").UseCollectionResult;

package/dist/esm/index.js

@@ -6,8 +6,9 @@
 // React Native platform adapter and keychain-backed session storage.
 export * from '@koolbase/core';
 export { reactNativePlatform } from './platform.js';
-import { KoolbaseAuth, KoolbaseDatabase, KoolbaseFiscal, KoolbaseStorage, KoolbaseRealtime, KoolbaseFunctions, KoolbaseFlags, KoolbaseAnalytics, KoolbaseMessaging, getOrCreateDeviceId, setPlatform, } from '@koolbase/core';
+import { KoolbaseAuth, KoolbaseDatabase, KoolbaseFiscal, KoolbaseStorage, KoolbaseRealtime, KoolbaseFunctions, KoolbaseFlags, KoolbaseAnalytics, disabledAnalytics, KoolbaseMessaging, getOrCreateDeviceId, setPlatform, } from '@koolbase/core';
 import { reactNativePlatform } from './platform.js';
+import { createUseCollection } from './use-collection.js';
 let _auth = null;
 let _db = null;
 let _storage = null;
@@ -16,6 +17,8 @@ let _realtime = null;
 let _functions = null;
 let _flags = null;
 let _analytics = null;
+// While analytics is off, calls are harmless no-ops rather than a crash.
+const analyticsOff = disabledAnalytics();
 let _messaging = null;
 let _initialized = false;
 // The in-flight initialize, so overlapping callers await the same one.
@@ -57,7 +60,8 @@ export const Koolbase = {
             const deviceId = await getOrCreateDeviceId();
             _flags = new KoolbaseFlags(config, deviceId);
             // Initialize analytics
-            if (config.analyticsEnabled !== false) {
+            // Opt-in: nothing is sent unless the app asks for it.
+            if (config.analyticsEnabled === true) {
                 _analytics = new KoolbaseAnalytics(config, () => _auth?.currentUser?.id ?? null);
                 await _analytics.init(config.appVersion);
             }
@@ -119,7 +123,7 @@ export const Koolbase = {
     },
     get analytics() {
         ensureInitialized();
-        return _analytics;
+        return _analytics ?? analyticsOff;
     },
     get messaging() {
         ensureInitialized();
@@ -131,3 +135,13 @@ export const Koolbase = {
     },
 };
 export { SecureAuthStorage } from './auth-storage.js';
+/**
+ * A collection as React state: loading, loaded or error, with refresh and
+ * loadMore. Equality filters only for now: `where: { field: value }`.
+ * Use it after Koolbase.initialize() (in an exported app, inside KoolbaseRoot).
+ *
+ * ```tsx
+ * const songs = useCollection('songs', { where: { genre: 'jazz' }, orderBy: 'title' });
+ * ```
+ */
+export const useCollection = createUseCollection(() => Koolbase.db);

package/dist/esm/use-collection.d.ts

@@ -0,0 +1,12 @@
+import { type CollectionQuery, type CollectionState, type KoolbaseDatabase } from '@koolbase/core';
+export interface UseCollectionResult extends CollectionState {
+    /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+    /**
+     * The next page, appended, while hasMore. If rows are added or removed on
+     * the server between pages, one can be skipped until refresh(); none is
+     * ever shown twice.
+     */
+    loadMore: () => Promise<void>;
+}
+export declare function createUseCollection(getDb: () => Pick<KoolbaseDatabase, 'query'>): (collection: string, query?: CollectionQuery) => UseCollectionResult;

package/dist/esm/use-collection.js

@@ -0,0 +1,36 @@
+// useCollection: a Koolbase collection as React state.
+//
+// A thin wrapper. Everything about getting the records right lives in
+// @koolbase/core's KoolbaseCollectionController, which is tested there; this
+// file only ties one controller's lifetime to a component's.
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { KoolbaseCollectionController, collectionQueryKey, initialCollectionState, } from '@koolbase/core';
+const noop = () => { };
+const done = () => Promise.resolve();
+export function createUseCollection(getDb) {
+    return function useCollection(collection, query = {}) {
+        // The query as a value: an inline `where` object is a new object every
+        // render, and must not start a new fetch every render.
+        const key = collectionQueryKey(collection, query);
+        const [current, setCurrent] = useState(null);
+        useEffect(() => {
+            // Created here, not during render. Under React strict mode an effect
+            // runs, cleans up and runs again; each run gets its own controller, so
+            // the one left running is never one that was already disposed.
+            const controller = new KoolbaseCollectionController(getDb(), collection, query);
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+            // Depends on key alone: key is collection + query, as a value.
+        }, [key]);
+        // A controller from the previous key reads as a fresh load, never as
+        // the previous query's records.
+        const controller = current?.key === key ? current.controller : null;
+        const subscribe = useCallback((onChange) => (controller ? controller.subscribe(onChange) : noop), [controller]);
+        const getSnapshot = useCallback(() => (controller ? controller.getState() : initialCollectionState), [controller]);
+        const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+        const refresh = useCallback(() => (controller ? controller.refresh() : done()), [controller]);
+        const loadMore = useCallback(() => (controller ? controller.loadMore() : done()), [controller]);
+        return { ...state, refresh, loadMore };
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/react-native",
-  "version": "12.3.0",
-  "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
+  "version": "12.5.0",
+  "description": "React Native SDK for Koolbase \u2014 auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",
   "files": [
@@ -24,11 +24,12 @@
     "url": "https://github.com/koolbase/koolbase-react-native"
   },
   "dependencies": {
-    "@koolbase/core": "12.3.0"
+    "@koolbase/core": "12.5.0"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "^3.0.2",
     "@react-native-community/netinfo": "^12.0.1",
+    "react": ">=18.0.0",
     "react-native": ">=0.70.0",
     "react-native-keychain": ">=8.0.0"
   },