@pol-studios/db 1.0.31 → 1.0.33

package/dist/{DataLayerContext-Dc7nF2IG.d.ts → DataLayerContext-BwMk4VpG.d.ts}

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { SupabaseClient } from '@supabase/supabase-js';
 import { QueryClient } from '@tanstack/react-query';
 import { DatabaseSchema, QueryOptions, DataLayerConfig, TableStrategy, SyncStatus, SyncControl } from './core/index.js';
-import { P as PowerSyncDatabase } from './executor-Br27YZvl.js';
+import { P as PowerSyncDatabase } from './executor-YJw4m7Q7.js';
 
 /**
  * V3 Data Layer Adapter Types
@@ -318,6 +318,25 @@ declare class AdapterAutoDetector {
      * @returns Detection result with recommendation and reasoning
      */
     detect(): AutoDetectionResult;
+    /**
+     * Detect backend availability WITHOUT notifying listeners.
+     *
+     * This method is safe to call during React's render phase because it does not
+     * trigger state updates in other components. Use this method when you need to
+     * check backend status synchronously during render (e.g., in getAdapter()).
+     *
+     * The regular detect() method with listener notifications should only be called
+     * from useEffect or event handlers to avoid the React warning:
+     * "Cannot update a component while rendering a different component"
+     *
+     * @returns Detection result with recommendation and reasoning
+     */
+    detectSilent(): AutoDetectionResult;
+    /**
+     * Internal detection logic shared by detect() and detectSilent().
+     * @private
+     */
+    private performDetection;
     /**
      * Check if PowerSync is available.
      *
@@ -342,7 +361,8 @@ declare class AdapterAutoDetector {
      *
      * Prefers the sync status's isOnline property if available (from React Native NetInfo).
      * Falls back to navigator.onLine in browser environments.
-     * Returns true by default for other environments.
+     * Returns false by default for non-browser environments (React Native, Node.js, etc.)
+     * to ensure offline-first behavior works correctly.
      *
      * @returns Whether the device has network connectivity
      */
@@ -431,6 +451,50 @@ declare class AdapterAutoDetector {
  */
 declare function createAdapterAutoDetector(powerSyncDb: PowerSyncDatabase | null, supabase: SupabaseClient | null, options?: AutoDetectorOptions): AdapterAutoDetector;
 
+/**
+ * Minimal interface for sync tracking callbacks.
+ * Intentionally decoupled from the full SyncControl to keep
+ * the adapter layer independent of React context types.
+ */
+interface SyncTracker {
+    addPendingMutation: (entry: {
+        id: string;
+        table: string;
+        op: string;
+        opData?: unknown;
+        createdAt?: Date;
+    }) => void;
+    removePendingMutation: (id: string) => void;
+}
+/**
+ * Decorator that wraps a TableDataAdapter and automatically
+ * tracks pending mutations via SyncTracker callbacks.
+ *
+ * Read operations (query, queryById, subscribe) are passed
+ * through without modification. Mutation operations (insert,
+ * update, upsert, delete) are wrapped with addPendingMutation
+ * before the write and removePendingMutation on error.
+ *
+ * NOTE: The syncTracker can be null/undefined during initialization
+ * due to React's useEffect timing. The adapter handles this gracefully
+ * by using optional chaining - mutations still work, just without tracking.
+ */
+declare class SyncTrackingAdapter implements TableDataAdapter {
+    private readonly inner;
+    private readonly syncTracker;
+    readonly name: string;
+    constructor(inner: TableDataAdapter, syncTracker: SyncTracker | null | undefined);
+    query<T>(table: string, options: QueryOptions): Promise<AdapterQueryResult<T>>;
+    queryById<T>(table: string, id: string, options?: Pick<QueryOptions, "select">): Promise<T | null>;
+    subscribe<T>(table: string, options: QueryOptions, callback: (data: T[]) => void): () => void;
+    insert<T>(table: string, data: Partial<T>): Promise<T>;
+    update<T>(table: string, id: string, data: Partial<T>): Promise<T>;
+    upsert<T>(table: string, data: Partial<T>): Promise<T>;
+    delete(table: string, id: string): Promise<void>;
+    /** Get the underlying unwrapped adapter */
+    getInnerAdapter(): TableDataAdapter;
+}
+
 /**
  * V3 Data Layer Adapter Registry
  *
@@ -489,6 +553,14 @@ declare class AdapterRegistry {
      * Auto-detector instance for automatic backend selection
      */
     private autoDetector;
+    /**
+     * Sync tracker for mutation tracking
+     */
+    private syncTracker;
+    /**
+     * Sync tracking adapter that wraps PowerSync adapter
+     */
+    private syncTrackingAdapter;
     /**
      * Listeners for backend change events
      */
@@ -520,6 +592,17 @@ declare class AdapterRegistry {
      * @param adapter - PowerSync adapter implementation
      */
     setPowerSyncAdapter(adapter: TableDataAdapter): void;
+    /**
+     * Set the sync tracker for mutation tracking.
+     * When set, write operations on PowerSync tables will
+     * automatically track pending mutations.
+     *
+     * NOTE: This also clears the adapter cache to ensure any
+     * previously cached adapters (which may have been created
+     * before the sync tracker was available) are recreated
+     * with the new sync tracker on next access.
+     */
+    setSyncTracker(tracker: SyncTracker): void;
     /**
      * Set the Supabase adapter instance
      *
@@ -556,10 +639,11 @@ declare class AdapterRegistry {
      * - Auto-generates PowerSync alias as "CoreProfile" if not explicitly set
      *
      * @param table - The table name (may be schema-qualified like "core.Profile")
+     * @param operation - The operation type: 'read' uses fallback logic during init, 'write' always uses PowerSync for powersync tables
      * @returns The appropriate adapter for the table
      * @throws Error if adapters are not initialized
      */
-    getAdapter(table: string): TableDataAdapter;
+    getAdapter(table: string, operation?: 'read' | 'write'): TableDataAdapter;
     /**
      * Get the PowerSync adapter directly
      *
@@ -748,8 +832,8 @@ interface DataLayerStatus {
 interface DataLayerCoreContextValue {
     /** Adapter registry for getting table adapters */
     registry: AdapterRegistry;
-    /** Get adapter for a specific table */
-    getAdapter: (table: string) => TableDataAdapter;
+    /** Get adapter for a specific table (defaults to 'read' operation) */
+    getAdapter: (table: string, operation?: 'read' | 'write') => TableDataAdapter;
     /** PowerSync database instance (null when not available) */
     powerSync: PowerSyncDatabase | null;
     /** Supabase client (always available) */
@@ -782,8 +866,8 @@ interface DataLayerStatusContextValue {
 interface DataLayerContextValue {
     /** Adapter registry for getting table adapters */
     registry: AdapterRegistry;
-    /** Get adapter for a specific table */
-    getAdapter: (table: string) => TableDataAdapter;
+    /** Get adapter for a specific table (defaults to 'read' operation) */
+    getAdapter: (table: string, operation?: 'read' | 'write') => TableDataAdapter;
     /** PowerSync database instance (null when not available) */
     powerSync: PowerSyncDatabase | null;
     /** Supabase client (always available) */
@@ -822,4 +906,4 @@ declare const DataLayerStatusContext: react.Context<DataLayerStatusContextValue>
  */
 declare const DataLayerContext: react.Context<DataLayerContextValue>;
 
-export { type AdapterQueryResult as A, BackendStatus as B, type CapableDataAdapter as C, DataLayerContext as D, type SyncStatusInfo as S, type TableDataAdapter as T, type AdapterConfig as a, type AdapterFactory as b, type AdapterCapabilities as c, type AdapterDependencies as d, type AdapterStrategyType as e, ADAPTER_STRATEGIES as f, AdapterRegistry as g, createAdapterRegistry as h, AdapterAutoDetector as i, createAdapterAutoDetector as j, type AutoDetectionResult as k, type AutoDetectorOptions as l, type BackendChangeListener as m, DataLayerCoreContext as n, DataLayerStatusContext as o, type DataLayerContextValue as p, type DataLayerCoreContextValue as q, type DataLayerStatusContextValue as r, type DataLayerStatus as s };
+export { type AdapterQueryResult as A, BackendStatus as B, type CapableDataAdapter as C, DataLayerContext as D, type SyncStatusInfo as S, type TableDataAdapter as T, type AdapterConfig as a, type AdapterFactory as b, type AdapterCapabilities as c, type AdapterDependencies as d, type AdapterStrategyType as e, ADAPTER_STRATEGIES as f, AdapterRegistry as g, createAdapterRegistry as h, AdapterAutoDetector as i, createAdapterAutoDetector as j, type AutoDetectionResult as k, type AutoDetectorOptions as l, type BackendChangeListener as m, SyncTrackingAdapter as n, type SyncTracker as o, DataLayerCoreContext as p, DataLayerStatusContext as q, type DataLayerContextValue as r, type DataLayerCoreContextValue as s, type DataLayerStatusContextValue as t, type DataLayerStatus as u };

package/dist/{UserMetadataContext-B8gVWGMl.d.ts → UserMetadataContext-pQb3A8_Q.d.ts}

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { D as Database } from './useSupabase-DvWVuHHE.js';
+import { D as Database } from './useSupabase-DSZNeXnF.js';
 
 declare function useLiveChangesIndicator(value: any, field: string | undefined): [boolean, string];
 

package/dist/{UserMetadataContext-DntmpK41.d.ts → UserMetadataContext-yLZQu24J.d.ts}

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { D as Database } from './useSupabase-DvWVuHHE.js';
+import { D as Database } from './useSupabase-DSZNeXnF.js';
 
 type UserMetadataRow = Database["core"]["Tables"]["UserMetadata"]["Row"];
 type UserMetadataInsert = Database["core"]["Tables"]["UserMetadata"]["Insert"];

package/dist/auth/context.d.ts

@@ -3,9 +3,9 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { d as EntityType, b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissions-DwFt4tUd.js';
-export { U as UserMetadataContextType, e as UserMetadataInsert, f as UserMetadataProvider, g as UserMetadataRow, h as UserMetadataUpdate, u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue, d as userMetadataContext } from '../UserMetadataContext-DntmpK41.js';
+export { U as UserMetadataContextType, e as UserMetadataInsert, f as UserMetadataProvider, g as UserMetadataRow, h as UserMetadataUpdate, u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue, d as userMetadataContext } from '../UserMetadataContext-yLZQu24J.js';
 import '@supabase/supabase-js';
-import '../useSupabase-DvWVuHHE.js';
+import '../useSupabase-DSZNeXnF.js';
 import '@supabase/supabase-js/dist/module/lib/types.js';
 
 interface AuthProviderProps {

package/dist/auth/context.js

@@ -11,15 +11,12 @@ import {
   useUserMetadataState,
   useUserMetadataValue,
   userMetadataContext
-} from "../chunk-WX4ABYIF.js";
-import "../chunk-VGEMLNNM.js";
-import "../chunk-GC3TBUWE.js";
+} from "../chunk-E6JL3RUF.js";
 import "../chunk-J4ZVCXZ4.js";
-import "../chunk-OQ7U6EQ3.js";
-import "../chunk-H6365JPC.js";
-import "../chunk-3PJTNH2L.js";
-import "../chunk-5EFDS7SR.js";
-import "../chunk-P4UZ7IXC.js";
+import "../chunk-YUX6RGLZ.js";
+import "../chunk-AKIRHA4Q.js";
+import "../chunk-DMVUEJG2.js";
+import "../chunk-7D4SUZUM.js";
 export {
   AuthProvider,
   PermissionProvider,

package/dist/auth/guards.d.ts

@@ -2,7 +2,7 @@ import { b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissi
 
 /**
  * Check if a user has access to a specific permission key.
- * Owners bypass all permission checks.
+ * Super-admin key (*:*:*) bypasses all permission checks.
  *
  * @param accessKeys - Array of access keys the user has
  * @param key - The access key to check for
@@ -17,8 +17,8 @@ import { b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissi
  * const canAccess = hasAccess(['admin', 'viewer'], 'admin'); // true
  * const cannotAccess = hasAccess(['viewer'], 'admin'); // false
  *
- * // Owner bypasses all checks
- * const ownerAccess = hasAccess(['owner'], 'any-key'); // true
+ * // Super-admin key bypasses all checks
+ * const superAdminAccess = hasAccess(['*:*:*'], 'any-key'); // true
  *
  * // Empty key always returns true (no permission required)
  * const noKeyRequired = hasAccess(['viewer'], ''); // true
@@ -70,12 +70,12 @@ declare function hasAllAccess(accessKeys: string[] | undefined | null, keys: str
 
 /**
  * Check if a user has entity-level access based on permission check result.
- * Owners (users with 'owner' access key) bypass entity permissions entirely.
+ * Super-admin key (*:*:*) bypasses entity permissions entirely.
  *
  * @param permission - The permission check result from getPermission/usePermission
  * @param action - The action to check for
  * @param options - Additional options for the check
- * @param options.accessKeys - User's access keys (for owner check)
+ * @param options.accessKeys - User's access keys (for super-admin check)
  * @param options.isArchived - Whether the user is archived
  * @param options.isSuspended - Whether the user is suspended
  * @returns boolean - true if user has permission for the action
@@ -86,10 +86,10 @@ declare function hasAllAccess(accessKeys: string[] | undefined | null, keys: str
  * const permission = await getPermission('Project', 123);
  * const canEdit = hasEntityAccess(permission, 'edit');
  *
- * // With owner bypass
- * const canEditAsOwner = hasEntityAccess(permission, 'edit', {
- *   accessKeys: ['owner'],
- * }); // true, owners bypass all checks
+ * // With super-admin bypass
+ * const canEditAsSuperAdmin = hasEntityAccess(permission, 'edit', {
+ *   accessKeys: ['*:*:*'],
+ * }); // true, super-admin bypasses all checks
  *
  * // Check loading state
  * if (permission.isLoading) {

package/dist/auth/guards.js

@@ -7,9 +7,8 @@ import {
   hasEntityAccess,
   isEntityAccessDenied,
   isPermissionLoaded
-} from "../chunk-HAWJTZCK.js";
-import "../chunk-OQ7U6EQ3.js";
-import "../chunk-P4UZ7IXC.js";
+} from "../chunk-RT4O5H2E.js";
+import "../chunk-7D4SUZUM.js";
 export {
   hasAccess,
   hasAllAccess,

package/dist/auth/hooks.d.ts

@@ -1,10 +1,10 @@
 import { User } from '@supabase/supabase-js';
 import { S as SetupAuthContext, E as EffectivePermission } from '../setupAuthContext-B76nbIP6.js';
 import { d as EntityType, a as EntityAction, b as EntityPermissionCheck } from '../EntityPermissions-DwFt4tUd.js';
-export { u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue } from '../UserMetadataContext-DntmpK41.js';
+export { u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue } from '../UserMetadataContext-yLZQu24J.js';
 import 'react';
 import 'react/jsx-runtime';
-import '../useSupabase-DvWVuHHE.js';
+import '../useSupabase-DSZNeXnF.js';
 import '@supabase/supabase-js/dist/module/lib/types.js';
 
 /**

package/dist/auth/hooks.js

@@ -11,21 +11,18 @@ import {
   usePermissionLoading,
   usePermissionsBatch,
   useSetupAuth
-} from "../chunk-5BLKZUKM.js";
+} from "../chunk-PNC6CG5U.js";
 import {
   useSetUserMetadata,
   useUserMetadata,
   useUserMetadataState,
   useUserMetadataValue
-} from "../chunk-WX4ABYIF.js";
-import "../chunk-VGEMLNNM.js";
-import "../chunk-GC3TBUWE.js";
+} from "../chunk-E6JL3RUF.js";
 import "../chunk-J4ZVCXZ4.js";
-import "../chunk-OQ7U6EQ3.js";
-import "../chunk-H6365JPC.js";
-import "../chunk-3PJTNH2L.js";
-import "../chunk-5EFDS7SR.js";
-import "../chunk-P4UZ7IXC.js";
+import "../chunk-YUX6RGLZ.js";
+import "../chunk-AKIRHA4Q.js";
+import "../chunk-DMVUEJG2.js";
+import "../chunk-7D4SUZUM.js";
 export {
   useAuth,
   useCanCreate,

package/dist/auth/index.d.ts

@@ -1,11 +1,11 @@
 export { EntityWithPermission, useAuth, useCanCreate, useCanDelete, useCanEdit, useCanShare, useCanView, useInvalidatePermission, usePermission, usePermissionCheck, usePermissionLoading, usePermissionsBatch, useSetupAuth } from './hooks.js';
 export { P as Profile, a as ProfileStatus, S as SetupAuthContext, b as SetupAuthContextProviderProps, s as setupAuthContext } from '../setupAuthContext-B76nbIP6.js';
 export { AuthProvider, AuthProviderProps, EntityPermissionContextValue, PermissionContextValue, PermissionProvider, entityPermissionContext, permissionContext, usePermissions } from './context.js';
-export { U as UserMetadataContextType, e as UserMetadataInsert, f as UserMetadataProvider, g as UserMetadataRow, h as UserMetadataUpdate, u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue, d as userMetadataContext } from '../UserMetadataContext-DntmpK41.js';
+export { U as UserMetadataContextType, e as UserMetadataInsert, f as UserMetadataProvider, g as UserMetadataRow, h as UserMetadataUpdate, u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue, d as userMetadataContext } from '../UserMetadataContext-yLZQu24J.js';
 export { hasAccess, hasAllAccess, hasAllEntityAccess, hasAnyAccess, hasAnyEntityAccess, hasEntityAccess, isEntityAccessDenied, isPermissionLoaded } from './guards.js';
 export { E as EntityAccessRecord, a as EntityAction, b as EntityPermissionCheck, c as EntityPermissionLevel, d as EntityType, P as PermissionEffect } from '../EntityPermissions-DwFt4tUd.js';
 import '@supabase/supabase-js';
 import 'react';
 import 'react/jsx-runtime';
-import '../useSupabase-DvWVuHHE.js';
+import '../useSupabase-DSZNeXnF.js';
 import '@supabase/supabase-js/dist/module/lib/types.js';

package/dist/auth/index.js

@@ -12,7 +12,7 @@ import {
   usePermissionLoading,
   usePermissionsBatch,
   useSetupAuth
-} from "../chunk-5BLKZUKM.js";
+} from "../chunk-PNC6CG5U.js";
 import {
   AuthProvider,
   PermissionProvider,
@@ -26,8 +26,7 @@ import {
   useUserMetadataState,
   useUserMetadataValue,
   userMetadataContext
-} from "../chunk-WX4ABYIF.js";
-import "../chunk-VGEMLNNM.js";
+} from "../chunk-E6JL3RUF.js";
 import {
   hasAccess,
   hasAllAccess,
@@ -37,14 +36,12 @@ import {
   hasEntityAccess,
   isEntityAccessDenied,
   isPermissionLoaded
-} from "../chunk-HAWJTZCK.js";
-import "../chunk-GC3TBUWE.js";
+} from "../chunk-RT4O5H2E.js";
 import "../chunk-J4ZVCXZ4.js";
-import "../chunk-OQ7U6EQ3.js";
-import "../chunk-H6365JPC.js";
-import "../chunk-3PJTNH2L.js";
-import "../chunk-5EFDS7SR.js";
-import "../chunk-P4UZ7IXC.js";
+import "../chunk-YUX6RGLZ.js";
+import "../chunk-AKIRHA4Q.js";
+import "../chunk-DMVUEJG2.js";
+import "../chunk-7D4SUZUM.js";
 export {
   AuthProvider,
   PermissionProvider,