@taladb/react 0.9.2 → 0.9.3

package/dist/index.d.mts

@@ -1,10 +1,42 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { TalaDB, OpenDBOptions, Document, Collection, Filter } from 'taladb';
+import { CollectionOptions, Document, TalaDB, OpenDBOptions, Collection, Filter } from 'taladb';
 
-type TalaDBProviderProps = {
+/**
+ * Per-collection options (`schema`, `syncSchema`, `migrateDocument`, …), keyed by
+ * collection name.
+ *
+ * Register them once on the provider and every hook below it — `useCollection`,
+ * and therefore `useFind`, `useQuery` and `useMutation` — resolves a *configured*
+ * collection. Without this, those hooks call `db.collection(name)` with no
+ * options, so a hook-driven write silently skips the strict `schema` validation
+ * and the `_v` stamp that `db.collection(name, { … })` would have applied.
+ */
+type CollectionRegistry = Record<string, CollectionOptions<any>>;
+/** Resolves the registered options for a collection. Stable across renders. */
+interface CollectionResolver {
+    get<T extends Document>(name: string): CollectionOptions<T> | undefined;
+}
+declare function useCollectionOptions(): CollectionResolver;
+type SharedProps = {
     children: ReactNode;
-} & ({
+    /**
+     * Per-collection options, keyed by collection name — see {@link CollectionRegistry}.
+     *
+     * ```tsx
+     * <TalaDBProvider
+     *   name="app.db"
+     *   collections={{
+     *     bookings: { schema: BookingSchema, syncSchema: { version: 1 } },
+     *   }}
+     * >
+     * ```
+     * Treated as static configuration: read when a collection handle is first
+     * created, so an inline object here does not thrash live queries.
+     */
+    collections?: CollectionRegistry;
+};
+type TalaDBProviderProps = SharedProps & ({
     /** A TalaDB instance you opened yourself with `openDB()`. */
     db: TalaDB;
     name?: never;
@@ -57,17 +89,30 @@ declare function useTalaDB(): TalaDB;
 /**
  * Returns a stable `Collection<T>` handle from the nearest `<TalaDBProvider>`.
  *
- * The returned collection is memoised — the same object reference is returned
- * on every render unless the db instance or collection name changes. Pass it
- * directly to `useFind` or `useFindOne` without wrapping in `useMemo`.
+ * The collection is opened **with its registered options** — the `schema`,
+ * `syncSchema` and `migrateDocument` declared in the provider's `collections`
+ * prop, or the `options` passed here (which win). That is what makes a write
+ * through `useMutation` hard-fail on an invalid document and carry its `_v`
+ * shape version, exactly as `db.collection(name, { … })` does. Without it the
+ * hooks resolve a bare, unconfigured handle and silently skip validation.
  *
- * @param name  The collection name (e.g. `'articles'`).
+ * The returned collection is memoised — the same object reference is returned on
+ * every render unless the db instance or collection name changes. Pass it
+ * directly to `useFind` or `useFindOne` without wrapping in `useMemo`. Options
+ * are read when the handle is first created and treated as static configuration,
+ * so an inline `{ schema }` object cannot thrash live-query subscriptions.
+ *
+ * @param name     The collection name (e.g. `'articles'`).
+ * @param options  Per-call options; overrides the provider's registry entry.
  *
  * @example
+ * // Registered once on the provider — every hook below it picks this up:
+ * <TalaDBProvider name="app.db" collections={{ articles: { schema: Article } }}>
+ *
  * const articles = useCollection<Article>('articles')
  * const { data, loading } = useFind(articles, { locale: 'en' })
  */
-declare function useCollection<T extends Document>(name: string): Collection<T>;
+declare function useCollection<T extends Document>(name: string, options?: CollectionOptions<T>): Collection<T>;
 
 interface FindResult<T> {
     /** The current matching documents. Empty array while loading. */
@@ -347,4 +392,4 @@ interface MutationResult<T extends Document> {
  */
 declare function useMutation<T extends Document>(options: UseMutationOptions): MutationResult<T>;
 
-export { type FindOneResult, type FindResult, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReadSource, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useCollection, useFind, useFindOne, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };
+export { type CollectionRegistry, type CollectionResolver, type FindOneResult, type FindResult, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReadSource, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useCollection, useCollectionOptions, useFind, useFindOne, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };

package/dist/index.d.ts

@@ -1,10 +1,42 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { TalaDB, OpenDBOptions, Document, Collection, Filter } from 'taladb';
+import { CollectionOptions, Document, TalaDB, OpenDBOptions, Collection, Filter } from 'taladb';
 
-type TalaDBProviderProps = {
+/**
+ * Per-collection options (`schema`, `syncSchema`, `migrateDocument`, …), keyed by
+ * collection name.
+ *
+ * Register them once on the provider and every hook below it — `useCollection`,
+ * and therefore `useFind`, `useQuery` and `useMutation` — resolves a *configured*
+ * collection. Without this, those hooks call `db.collection(name)` with no
+ * options, so a hook-driven write silently skips the strict `schema` validation
+ * and the `_v` stamp that `db.collection(name, { … })` would have applied.
+ */
+type CollectionRegistry = Record<string, CollectionOptions<any>>;
+/** Resolves the registered options for a collection. Stable across renders. */
+interface CollectionResolver {
+    get<T extends Document>(name: string): CollectionOptions<T> | undefined;
+}
+declare function useCollectionOptions(): CollectionResolver;
+type SharedProps = {
     children: ReactNode;
-} & ({
+    /**
+     * Per-collection options, keyed by collection name — see {@link CollectionRegistry}.
+     *
+     * ```tsx
+     * <TalaDBProvider
+     *   name="app.db"
+     *   collections={{
+     *     bookings: { schema: BookingSchema, syncSchema: { version: 1 } },
+     *   }}
+     * >
+     * ```
+     * Treated as static configuration: read when a collection handle is first
+     * created, so an inline object here does not thrash live queries.
+     */
+    collections?: CollectionRegistry;
+};
+type TalaDBProviderProps = SharedProps & ({
     /** A TalaDB instance you opened yourself with `openDB()`. */
     db: TalaDB;
     name?: never;
@@ -57,17 +89,30 @@ declare function useTalaDB(): TalaDB;
 /**
  * Returns a stable `Collection<T>` handle from the nearest `<TalaDBProvider>`.
  *
- * The returned collection is memoised — the same object reference is returned
- * on every render unless the db instance or collection name changes. Pass it
- * directly to `useFind` or `useFindOne` without wrapping in `useMemo`.
+ * The collection is opened **with its registered options** — the `schema`,
+ * `syncSchema` and `migrateDocument` declared in the provider's `collections`
+ * prop, or the `options` passed here (which win). That is what makes a write
+ * through `useMutation` hard-fail on an invalid document and carry its `_v`
+ * shape version, exactly as `db.collection(name, { … })` does. Without it the
+ * hooks resolve a bare, unconfigured handle and silently skip validation.
  *
- * @param name  The collection name (e.g. `'articles'`).
+ * The returned collection is memoised — the same object reference is returned on
+ * every render unless the db instance or collection name changes. Pass it
+ * directly to `useFind` or `useFindOne` without wrapping in `useMemo`. Options
+ * are read when the handle is first created and treated as static configuration,
+ * so an inline `{ schema }` object cannot thrash live-query subscriptions.
+ *
+ * @param name     The collection name (e.g. `'articles'`).
+ * @param options  Per-call options; overrides the provider's registry entry.
  *
  * @example
+ * // Registered once on the provider — every hook below it picks this up:
+ * <TalaDBProvider name="app.db" collections={{ articles: { schema: Article } }}>
+ *
  * const articles = useCollection<Article>('articles')
  * const { data, loading } = useFind(articles, { locale: 'en' })
  */
-declare function useCollection<T extends Document>(name: string): Collection<T>;
+declare function useCollection<T extends Document>(name: string, options?: CollectionOptions<T>): Collection<T>;
 
 interface FindResult<T> {
     /** The current matching documents. Empty array while loading. */
@@ -347,4 +392,4 @@ interface MutationResult<T extends Document> {
  */
 declare function useMutation<T extends Document>(options: UseMutationOptions): MutationResult<T>;
 
-export { type FindOneResult, type FindResult, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReadSource, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useCollection, useFind, useFindOne, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };
+export { type CollectionRegistry, type CollectionResolver, type FindOneResult, type FindResult, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReadSource, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useCollection, useCollectionOptions, useFind, useFindOne, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   ReplicationProvider: () => ReplicationProvider,
   TalaDBProvider: () => TalaDBProvider,
   useCollection: () => useCollection,
+  useCollectionOptions: () => useCollectionOptions,
   useFind: () => useFind,
   useFindOne: () => useFindOne,
   useMutation: () => useMutation,
@@ -48,9 +49,29 @@ module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
 var TalaDBContext = (0, import_react.createContext)(null);
+var CollectionOptionsContext = (0, import_react.createContext)({
+  get: () => void 0
+});
+function useCollectionOptions() {
+  return (0, import_react.useContext)(CollectionOptionsContext);
+}
+function CollectionOptionsProvider({
+  collections,
+  children
+}) {
+  const latest = (0, import_react.useRef)(collections);
+  latest.current = collections;
+  const resolver = (0, import_react.useMemo)(
+    () => ({
+      get: (name) => latest.current?.[name]
+    }),
+    []
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CollectionOptionsContext.Provider, { value: resolver, children });
+}
 function TalaDBProvider(props) {
   if ("db" in props && props.db) {
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TalaDBContext.Provider, { value: props.db, children: props.children });
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TalaDBContext.Provider, { value: props.db, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CollectionOptionsProvider, { collections: props.collections, children: props.children }) });
   }
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NamedProvider, { ...props });
 }
@@ -58,6 +79,7 @@ function NamedProvider({
   name,
   options,
   fallback = null,
+  collections,
   children
 }) {
   const [db, setDb] = (0, import_react.useState)(null);
@@ -85,7 +107,7 @@ function NamedProvider({
   }, [name, optionsKey]);
   if (error !== null) throw error;
   if (db === null) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: fallback });
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TalaDBContext.Provider, { value: db, children });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TalaDBContext.Provider, { value: db, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CollectionOptionsProvider, { collections, children }) });
 }
 function useTalaDB() {
   const db = (0, import_react.useContext)(TalaDBContext);
@@ -97,9 +119,15 @@ function useTalaDB() {
 
 // src/useCollection.ts
 var import_react2 = require("react");
-function useCollection(name) {
+function useCollection(name, options) {
   const db = useTalaDB();
-  return (0, import_react2.useMemo)(() => db.collection(name), [db, name]);
+  const registry = useCollectionOptions();
+  const explicit = (0, import_react2.useRef)(options);
+  explicit.current = options;
+  return (0, import_react2.useMemo)(
+    () => db.collection(name, explicit.current ?? registry.get(name)),
+    [db, name, registry]
+  );
 }
 
 // src/useFind.ts
@@ -541,6 +569,7 @@ function useMutation(options) {
   ReplicationProvider,
   TalaDBProvider,
   useCollection,
+  useCollectionOptions,
   useFind,
   useFindOne,
   useMutation,

package/dist/index.mjs

@@ -1,12 +1,39 @@
 'use client';
 
 // src/context.tsx
-import { createContext, useContext, useEffect, useState } from "react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
 import { Fragment, jsx } from "react/jsx-runtime";
 var TalaDBContext = createContext(null);
+var CollectionOptionsContext = createContext({
+  get: () => void 0
+});
+function useCollectionOptions() {
+  return useContext(CollectionOptionsContext);
+}
+function CollectionOptionsProvider({
+  collections,
+  children
+}) {
+  const latest = useRef(collections);
+  latest.current = collections;
+  const resolver = useMemo(
+    () => ({
+      get: (name) => latest.current?.[name]
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsx(CollectionOptionsContext.Provider, { value: resolver, children });
+}
 function TalaDBProvider(props) {
   if ("db" in props && props.db) {
-    return /* @__PURE__ */ jsx(TalaDBContext.Provider, { value: props.db, children: props.children });
+    return /* @__PURE__ */ jsx(TalaDBContext.Provider, { value: props.db, children: /* @__PURE__ */ jsx(CollectionOptionsProvider, { collections: props.collections, children: props.children }) });
   }
   return /* @__PURE__ */ jsx(NamedProvider, { ...props });
 }
@@ -14,6 +41,7 @@ function NamedProvider({
   name,
   options,
   fallback = null,
+  collections,
   children
 }) {
   const [db, setDb] = useState(null);
@@ -41,7 +69,7 @@ function NamedProvider({
   }, [name, optionsKey]);
   if (error !== null) throw error;
   if (db === null) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
-  return /* @__PURE__ */ jsx(TalaDBContext.Provider, { value: db, children });
+  return /* @__PURE__ */ jsx(TalaDBContext.Provider, { value: db, children: /* @__PURE__ */ jsx(CollectionOptionsProvider, { collections, children }) });
 }
 function useTalaDB() {
   const db = useContext(TalaDBContext);
@@ -52,16 +80,22 @@ function useTalaDB() {
 }
 
 // src/useCollection.ts
-import { useMemo } from "react";
-function useCollection(name) {
+import { useMemo as useMemo2, useRef as useRef2 } from "react";
+function useCollection(name, options) {
   const db = useTalaDB();
-  return useMemo(() => db.collection(name), [db, name]);
+  const registry = useCollectionOptions();
+  const explicit = useRef2(options);
+  explicit.current = options;
+  return useMemo2(
+    () => db.collection(name, explicit.current ?? registry.get(name)),
+    [db, name, registry]
+  );
 }
 
 // src/useFind.ts
-import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useCallback, useRef as useRef3, useSyncExternalStore } from "react";
 function useFind(collection, filter) {
-  const snapshotRef = useRef({ data: [], loading: true, error: null });
+  const snapshotRef = useRef3({ data: [], loading: true, error: null });
   const filterKey = JSON.stringify(filter ?? null);
   const subscribe = useCallback(
     (notify) => {
@@ -83,9 +117,9 @@ function useFind(collection, filter) {
 }
 
 // src/useFindOne.ts
-import { useCallback as useCallback2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { useCallback as useCallback2, useRef as useRef4, useSyncExternalStore as useSyncExternalStore2 } from "react";
 function useFindOne(collection, filter) {
-  const snapshotRef = useRef2({ data: null, loading: true, error: null });
+  const snapshotRef = useRef4({ data: null, loading: true, error: null });
   const filterKey = JSON.stringify(filter);
   const subscribe = useCallback2(
     (notify) => {
@@ -110,8 +144,8 @@ import {
   createContext as createContext2,
   useContext as useContext2,
   useEffect as useEffect2,
-  useMemo as useMemo2,
-  useRef as useRef3
+  useMemo as useMemo3,
+  useRef as useRef5
 } from "react";
 
 // src/replication/engine.ts
@@ -170,7 +204,7 @@ import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 var ReplicationContext = createContext2(null);
 function ReplicationProvider({ children, ...config }) {
   const key = `${config.endpoint}|${config.pollMs ?? ""}|${JSON.stringify(config.paths ?? null)}|${JSON.stringify(config.prefetch ?? null)}|${config.prefetchMode ?? ""}|${config.prefetchConcurrency ?? ""}`;
-  const value = useMemo2(
+  const value = useMemo3(
     () => config,
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [key]
@@ -228,7 +262,7 @@ function PrefetchRunner() {
   const slices = normalizePrefetch(base?.prefetch);
   const mode = base?.prefetchMode ?? "once";
   const concurrency = Math.max(1, base?.prefetchConcurrency ?? 2);
-  const baseRef = useRef3(base);
+  const baseRef = useRef5(base);
   baseRef.current = base;
   const sig = JSON.stringify({ slices, mode, concurrency, endpoint: base?.endpoint ?? null });
   useEffect2(() => {
@@ -267,7 +301,7 @@ function PrefetchRunner() {
 }
 
 // src/useQuery.ts
-import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef4, useState as useState2 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef6, useState as useState2 } from "react";
 function useQuery(options) {
   const { collection, filter, source = "local-first" } = options;
   const networked = source !== "local-only";
@@ -281,7 +315,7 @@ function useQuery(options) {
     paths: options.paths,
     pollMs: options.pollMs
   });
-  const configRef = useRef4(config);
+  const configRef = useRef6(config);
   configRef.current = config;
   const [syncing, setSyncing] = useState2(false);
   const [syncError, setSyncError] = useState2(null);
@@ -320,7 +354,7 @@ function useQuery(options) {
 }
 
 // src/useQueries.ts
-import { useEffect as useEffect4, useRef as useRef5, useState as useState3 } from "react";
+import { useEffect as useEffect4, useRef as useRef7, useState as useState3 } from "react";
 var NOOP_REFETCH = async () => {
 };
 function emptyResult() {
@@ -346,9 +380,9 @@ function useQueries(queries) {
       pollMs: q.pollMs ?? null
     }))
   );
-  const queriesRef = useRef5(queries);
+  const queriesRef = useRef7(queries);
   queriesRef.current = queries;
-  const baseRef = useRef5(base);
+  const baseRef = useRef7(base);
   baseRef.current = base;
   const [results, setResults] = useState3(
     () => queries.map(() => emptyResult())
@@ -426,7 +460,7 @@ function useQueries(queries) {
 }
 
 // src/useMutation.ts
-import { useCallback as useCallback4, useEffect as useEffect5, useRef as useRef6, useState as useState4 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect5, useRef as useRef8, useState as useState4 } from "react";
 function useMutation(options) {
   const { collection, direction = "push", drainOnMount = true } = options;
   const db = useTalaDB();
@@ -437,7 +471,7 @@ function useMutation(options) {
     fetch: options.fetch,
     paths: options.paths
   });
-  const configRef = useRef6(config);
+  const configRef = useRef8(config);
   configRef.current = config;
   const [pending, setPending] = useState4(false);
   const [error, setError] = useState4(null);
@@ -502,6 +536,7 @@ export {
   ReplicationProvider,
   TalaDBProvider,
   useCollection,
+  useCollectionOptions,
   useFind,
   useFindOne,
   useMutation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/react",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "React hooks for TalaDB — useFind, useFindOne, and useCollection for React and React Native",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -41,7 +41,7 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "taladb": "^0.9.2"
+    "taladb": "^0.9.3"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
@@ -53,7 +53,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.0",
-    "taladb": "0.9.2"
+    "taladb": "0.9.3"
   },
   "scripts": {
     "build": "tsup",