@koolbase/core 12.9.0 → 12.10.0

package/dist/cjs/react/index.d.ts

@@ -0,0 +1,2 @@
+export { createUseCollection, type UseCollectionResult } from './use-collection.js';
+export { createUseRecord, type UseRecordResult } from './use-record.js';

package/dist/cjs/react/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUseRecord = exports.createUseCollection = void 0;
+// React hooks over core's controllers: ONE implementation, exported to apps by
+// @koolbase/react-native (from its root, as always) and @koolbase/js/react.
+// React only -- nothing native, nothing DOM. Deliberately not exported from
+// core's root entry, so importing @koolbase/core never loads React.
+var use_collection_js_1 = require("./use-collection.js");
+Object.defineProperty(exports, "createUseCollection", { enumerable: true, get: function () { return use_collection_js_1.createUseCollection; } });
+var use_record_js_1 = require("./use-record.js");
+Object.defineProperty(exports, "createUseRecord", { enumerable: true, get: function () { return use_record_js_1.createUseRecord; } });

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

@@ -0,0 +1,12 @@
+import { type CollectionQuery, type CollectionState, type KoolbaseDatabase } from '../index.js';
+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/react/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 index_js_1 = require("../index.js");
+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, index_js_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 index_js_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() : index_js_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/cjs/react/use-record.d.ts

@@ -0,0 +1,6 @@
+import { type KoolbaseDatabase, type RecordState } from '../index.js';
+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/react/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 index_js_1 = require("../index.js");
+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 index_js_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() : index_js_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/react/index.d.ts

@@ -0,0 +1,2 @@
+export { createUseCollection, type UseCollectionResult } from './use-collection.js';
+export { createUseRecord, type UseRecordResult } from './use-record.js';

package/dist/esm/react/index.js

@@ -0,0 +1,6 @@
+// React hooks over core's controllers: ONE implementation, exported to apps by
+// @koolbase/react-native (from its root, as always) and @koolbase/js/react.
+// React only -- nothing native, nothing DOM. Deliberately not exported from
+// core's root entry, so importing @koolbase/core never loads React.
+export { createUseCollection } from './use-collection.js';
+export { createUseRecord } from './use-record.js';

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

@@ -0,0 +1,12 @@
+import { type CollectionQuery, type CollectionState, type KoolbaseDatabase } from '../index.js';
+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/react/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 '../index.js';
+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/dist/esm/react/use-record.d.ts

@@ -0,0 +1,6 @@
+import { type KoolbaseDatabase, type RecordState } from '../index.js';
+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/react/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 '../index.js';
+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,11 +1,12 @@
 {
   "name": "@koolbase/core",
-  "version": "12.9.0",
+  "version": "12.10.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "react"
   ],
   "scripts": {
     "build": "node ../../scripts/build-package.js core",
@@ -39,7 +40,25 @@
         "default": "./dist/cjs/index.js"
       }
     },
+    "./react": {
+      "import": {
+        "types": "./dist/esm/react/index.d.ts",
+        "default": "./dist/esm/react/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/react/index.d.ts",
+        "default": "./dist/cjs/react/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
 }

package/react/package.json

@@ -0,0 +1,7 @@
+{
+  "//": "For resolvers that ignore \"exports\" (TypeScript node10, older bundlers): the ./react entry.",
+  "main": "../dist/cjs/react/index.js",
+  "module": "../dist/esm/react/index.js",
+  "types": "../dist/cjs/react/index.d.ts",
+  "sideEffects": false
+}