@koolbase/react-native 12.5.1 → 12.6.0

package/dist/cjs/index.d.ts

@@ -29,3 +29,15 @@ export type { UseCollectionResult } from './use-collection.js';
  * ```
  */
 export declare const useCollection: (collection: string, query?: import("@koolbase/core").CollectionQuery) => import("./use-collection.js").UseCollectionResult;
+export type { UseRecordResult } from './use-record.js';
+/**
+ * One record, by id, as React state: loading, loaded, notFound or error,
+ * with refresh. notFound covers a missing id, a record that does not exist,
+ * one this user may not read (the API does not tell them apart) and a record
+ * from a different collection. Use it after Koolbase.initialize().
+ *
+ * ```tsx
+ * const song = useRecord('songs', songId);
+ * ```
+ */
+export declare const useRecord: (collection: string, id: string | null | undefined) => import("./use-record.js").UseRecordResult;

package/dist/cjs/index.js

@@ -20,13 +20,14 @@ 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.useCollection = exports.SecureAuthStorage = exports.Koolbase = exports.reactNativePlatform = void 0;
+exports.useRecord = 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");
+const use_record_js_1 = require("./use-record.js");
 let _auth = null;
 let _db = null;
 let _storage = null;
@@ -164,3 +165,14 @@ Object.defineProperty(exports, "SecureAuthStorage", { enumerable: true, get: fun
  * ```
  */
 exports.useCollection = (0, use_collection_js_1.createUseCollection)(() => exports.Koolbase.db);
+/**
+ * One record, by id, as React state: loading, loaded, notFound or error,
+ * with refresh. notFound covers a missing id, a record that does not exist,
+ * one this user may not read (the API does not tell them apart) and a record
+ * from a different collection. Use it after Koolbase.initialize().
+ *
+ * ```tsx
+ * const song = useRecord('songs', songId);
+ * ```
+ */
+exports.useRecord = (0, use_record_js_1.createUseRecord)(() => exports.Koolbase.db);

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

@@ -0,0 +1,6 @@
+import { type KoolbaseDatabase, type RecordState } from '@koolbase/core';
+export interface UseRecordResult extends RecordState {
+    /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+}
+export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined) => UseRecordResult;

package/dist/cjs/use-record.js

@@ -0,0 +1,35 @@
+"use strict";
+// useRecord: one Koolbase record, by id, as React state.
+//
+// A thin wrapper, like useCollection: everything about getting the record
+// right lives in @koolbase/core's KoolbaseRecordController, tested there;
+// this file only ties one controller's lifetime to a component's.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUseRecord = createUseRecord;
+const react_1 = require("react");
+const core_1 = require("@koolbase/core");
+const noop = () => { };
+const done = () => Promise.resolve();
+function createUseRecord(getDb) {
+    return function useRecord(collection, id) {
+        const key = JSON.stringify([collection, id ?? '']);
+        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, and each run gets its own controller.
+            const controller = new core_1.KoolbaseRecordController(getDb(), collection, id ?? '');
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+            // Depends on key alone: key is collection + id, as a value.
+        }, [key]);
+        // A controller from the previous key reads as a fresh load, never as the
+        // previous record.
+        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.initialRecordState), [controller]);
+        const state = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+        const refresh = (0, react_1.useCallback)(() => (controller ? controller.refresh() : done()), [controller]);
+        return { ...state, refresh };
+    };
+}

package/dist/esm/index.d.ts

@@ -29,3 +29,15 @@ export type { UseCollectionResult } from './use-collection.js';
  * ```
  */
 export declare const useCollection: (collection: string, query?: import("@koolbase/core").CollectionQuery) => import("./use-collection.js").UseCollectionResult;
+export type { UseRecordResult } from './use-record.js';
+/**
+ * One record, by id, as React state: loading, loaded, notFound or error,
+ * with refresh. notFound covers a missing id, a record that does not exist,
+ * one this user may not read (the API does not tell them apart) and a record
+ * from a different collection. Use it after Koolbase.initialize().
+ *
+ * ```tsx
+ * const song = useRecord('songs', songId);
+ * ```
+ */
+export declare const useRecord: (collection: string, id: string | null | undefined) => import("./use-record.js").UseRecordResult;

package/dist/esm/index.js

@@ -9,6 +9,7 @@ export { reactNativePlatform } from './platform.js';
 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';
+import { createUseRecord } from './use-record.js';
 let _auth = null;
 let _db = null;
 let _storage = null;
@@ -145,3 +146,14 @@ export { SecureAuthStorage } from './auth-storage.js';
  * ```
  */
 export const useCollection = createUseCollection(() => Koolbase.db);
+/**
+ * One record, by id, as React state: loading, loaded, notFound or error,
+ * with refresh. notFound covers a missing id, a record that does not exist,
+ * one this user may not read (the API does not tell them apart) and a record
+ * from a different collection. Use it after Koolbase.initialize().
+ *
+ * ```tsx
+ * const song = useRecord('songs', songId);
+ * ```
+ */
+export const useRecord = createUseRecord(() => Koolbase.db);

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

@@ -0,0 +1,6 @@
+import { type KoolbaseDatabase, type RecordState } from '@koolbase/core';
+export interface UseRecordResult extends RecordState {
+    /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+}
+export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined) => UseRecordResult;

package/dist/esm/use-record.js

@@ -0,0 +1,32 @@
+// useRecord: one Koolbase record, by id, as React state.
+//
+// A thin wrapper, like useCollection: everything about getting the record
+// right lives in @koolbase/core's KoolbaseRecordController, tested there;
+// this file only ties one controller's lifetime to a component's.
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { KoolbaseRecordController, initialRecordState, } from '@koolbase/core';
+const noop = () => { };
+const done = () => Promise.resolve();
+export function createUseRecord(getDb) {
+    return function useRecord(collection, id) {
+        const key = JSON.stringify([collection, id ?? '']);
+        const [current, setCurrent] = useState(null);
+        useEffect(() => {
+            // Created here, not during render: under React strict mode an effect
+            // runs, cleans up and runs again, and each run gets its own controller.
+            const controller = new KoolbaseRecordController(getDb(), collection, id ?? '');
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+            // Depends on key alone: key is collection + id, as a value.
+        }, [key]);
+        // A controller from the previous key reads as a fresh load, never as the
+        // previous record.
+        const controller = current?.key === key ? current.controller : null;
+        const subscribe = useCallback((onChange) => (controller ? controller.subscribe(onChange) : noop), [controller]);
+        const getSnapshot = useCallback(() => (controller ? controller.getState() : initialRecordState), [controller]);
+        const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+        const refresh = useCallback(() => (controller ? controller.refresh() : done()), [controller]);
+        return { ...state, refresh };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/react-native",
-  "version": "12.5.1",
+  "version": "12.6.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",
@@ -24,7 +24,7 @@
     "url": "https://github.com/koolbase/koolbase-react-native"
   },
   "dependencies": {
-    "@koolbase/core": "12.5.1"
+    "@koolbase/core": "12.6.0"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "^2.2.0 || ^3.0.2",