local-lite 0.0.14 → 0.0.15

package/dist/access/client.d.ts

@@ -0,0 +1,9 @@
+import { AccessGuard } from './guard.js';
+/**
+ * Wraps a LocalFirstClient with an AccessGuard.
+ * Intercepts CRUD queries and mutations, asserting permissions before writes and
+ * filtering unauthorized rows or restricted fields on reads.
+ */
+export declare function withAccess<T extends {
+    [key: string]: any;
+}>(client: T, guard: AccessGuard): T;

package/dist/access/client.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAccess = withAccess;
+/**
+ * Wraps a LocalFirstClient with an AccessGuard.
+ * Intercepts CRUD queries and mutations, asserting permissions before writes and
+ * filtering unauthorized rows or restricted fields on reads.
+ */
+function withAccess(client, guard) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'insert') {
+                return async (tableName, rowIdOrPayload, payloadOrOptions, options) => {
+                    const payload = typeof rowIdOrPayload === 'string'
+                        ? payloadOrOptions || {}
+                        : rowIdOrPayload || {};
+                    guard.assertCan('create', tableName, payload);
+                    return target.insert(tableName, rowIdOrPayload, payloadOrOptions, options);
+                };
+            }
+            if (prop === 'update') {
+                return async (tableName, rowId, payload, options) => {
+                    guard.assertCan('update', tableName, { id: rowId, ...payload });
+                    return target.update(tableName, rowId, payload, options);
+                };
+            }
+            if (prop === 'delete') {
+                return async (tableName, rowId, options) => {
+                    guard.assertCan('delete', tableName, { id: rowId });
+                    return target.delete(tableName, rowId, options);
+                };
+            }
+            if (prop === 'findById') {
+                return async (tableName, id, options) => {
+                    const record = await target.findById(tableName, id, options);
+                    if (!record)
+                        return null;
+                    if (!guard.can('read', tableName, record)) {
+                        return null;
+                    }
+                    return guard.filterAllowedFields('read', tableName, record, record);
+                };
+            }
+            if (prop === 'findMany') {
+                return async (tableName, options) => {
+                    const records = await target.findMany(tableName, options);
+                    return guard.filterRows('read', tableName, records);
+                };
+            }
+            if (prop === 'accessGuard') {
+                return guard;
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}

package/dist/access/engine.d.ts

@@ -0,0 +1,2 @@
+import { AccessPolicyDefinition, AccessEngine } from './types.js';
+export declare function defineAccessRules<TUser = any>(policy: AccessPolicyDefinition<TUser>): AccessEngine<TUser>;

package/dist/access/engine.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAccessRules = defineAccessRules;
+const guard_js_1 = require("./guard.js");
+class RuleBuilderImpl {
+    rules = [];
+    addRule(inverted, actions, subjects, arg3, arg4) {
+        const actionList = Array.isArray(actions) ? actions : [actions];
+        const subjectList = Array.isArray(subjects) ? subjects : [subjects];
+        let options;
+        let predicate;
+        if (typeof arg3 === 'function') {
+            predicate = arg3;
+        }
+        else if (arg3 && typeof arg3 === 'object') {
+            options = arg3;
+            predicate = arg4;
+        }
+        this.rules.push({
+            inverted,
+            actions: actionList,
+            subjects: subjectList,
+            predicate,
+            fields: options?.fields,
+            description: options?.description,
+        });
+        return this;
+    }
+    can(action, subject, arg3, arg4) {
+        return this.addRule(false, action, subject, arg3, arg4);
+    }
+    cannot(action, subject, arg3, arg4) {
+        return this.addRule(true, action, subject, arg3, arg4);
+    }
+}
+function defineAccessRules(policy) {
+    const createGuard = (user) => {
+        const builder = new RuleBuilderImpl();
+        policy(builder, user);
+        return new guard_js_1.AccessGuard(user, builder.rules);
+    };
+    return {
+        createGuard,
+        for: createGuard,
+    };
+}

package/dist/access/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class AccessDeniedError extends Error {
+    readonly action: string;
+    readonly subject: string;
+    readonly fields?: string[];
+    readonly record?: any;
+    readonly reason?: string;
+    constructor(options: {
+        action: string;
+        subject: string;
+        fields?: string[];
+        record?: any;
+        reason?: string;
+    });
+}

package/dist/access/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessDeniedError = void 0;
+class AccessDeniedError extends Error {
+    action;
+    subject;
+    fields;
+    record;
+    reason;
+    constructor(options) {
+        const fieldsText = options.fields && options.fields.length > 0 ? ` (fields: ${options.fields.join(', ')})` : '';
+        const message = options.reason ||
+            `Access denied: cannot perform action '${options.action}' on subject '${options.subject}'${fieldsText}.`;
+        super(message);
+        this.name = 'AccessDeniedError';
+        this.action = options.action;
+        this.subject = options.subject;
+        this.fields = options.fields;
+        this.record = options.record;
+        this.reason = options.reason;
+    }
+}
+exports.AccessDeniedError = AccessDeniedError;

package/dist/access/guard.d.ts

@@ -0,0 +1,24 @@
+import { AccessAction, AccessRule, AccessSubject } from './types.js';
+export declare class AccessGuard<TUser = any> {
+    readonly user: TUser | null;
+    readonly rules: AccessRule<TUser>[];
+    constructor(user: TUser | null, rules: AccessRule<TUser>[]);
+    /**
+     * Evaluates if the current user has permission to perform an action on a subject.
+     */
+    can(action: AccessAction, subject: AccessSubject, record?: any): boolean;
+    cannot(action: AccessAction, subject: AccessSubject, record?: any): boolean;
+    assertCan(action: AccessAction, subject: AccessSubject, record?: any): void;
+    /**
+     * Check if a specific field is accessible for an action.
+     */
+    canAccessField(action: AccessAction, subject: AccessSubject, field: string, record?: any): boolean;
+    /**
+     * Strips restricted fields from an object based on rules.
+     */
+    filterAllowedFields<T extends Record<string, any>>(action: AccessAction, subject: AccessSubject, data: T, record?: any): Partial<T>;
+    /**
+     * Filters an array of rows, removing unauthorized records and stripping forbidden fields.
+     */
+    filterRows<T extends Record<string, any>>(action: AccessAction, subject: AccessSubject, rows: T[]): T[];
+}

package/dist/access/guard.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessGuard = void 0;
+const errors_js_1 = require("./errors.js");
+class AccessGuard {
+    user;
+    rules;
+    constructor(user, rules) {
+        this.user = user;
+        this.rules = rules;
+    }
+    /**
+     * Evaluates if the current user has permission to perform an action on a subject.
+     */
+    can(action, subject, record) {
+        let allowed = false;
+        for (const rule of this.rules) {
+            const actionMatches = rule.actions.includes('manage') ||
+                rule.actions.includes('all') ||
+                rule.actions.includes(action);
+            const subjectMatches = rule.subjects.includes('all') ||
+                rule.subjects.includes(subject);
+            if (!actionMatches || !subjectMatches) {
+                continue;
+            }
+            if (rule.predicate) {
+                try {
+                    if (!rule.predicate(record, this.user)) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            // If cannot rule matches (with no field filter), reject immediately
+            if (rule.inverted && (!rule.fields || rule.fields.length === 0)) {
+                return false;
+            }
+            // If can rule matches, mark allowed
+            if (!rule.inverted) {
+                allowed = true;
+            }
+        }
+        return allowed;
+    }
+    cannot(action, subject, record) {
+        return !this.can(action, subject, record);
+    }
+    assertCan(action, subject, record) {
+        if (!this.can(action, subject, record)) {
+            throw new errors_js_1.AccessDeniedError({ action, subject, record });
+        }
+    }
+    /**
+     * Check if a specific field is accessible for an action.
+     */
+    canAccessField(action, subject, field, record) {
+        if (!this.can(action, subject, record)) {
+            return false;
+        }
+        for (const rule of this.rules) {
+            if (!rule.inverted || !rule.fields || !rule.fields.includes(field)) {
+                continue;
+            }
+            const actionMatches = rule.actions.includes('manage') ||
+                rule.actions.includes('all') ||
+                rule.actions.includes(action);
+            const subjectMatches = rule.subjects.includes('all') ||
+                rule.subjects.includes(subject);
+            if (actionMatches && subjectMatches) {
+                if (!rule.predicate || rule.predicate(record, this.user)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Strips restricted fields from an object based on rules.
+     */
+    filterAllowedFields(action, subject, data, record) {
+        if (!data || typeof data !== 'object')
+            return data;
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (this.canAccessField(action, subject, key, record || data)) {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Filters an array of rows, removing unauthorized records and stripping forbidden fields.
+     */
+    filterRows(action, subject, rows) {
+        if (!Array.isArray(rows))
+            return [];
+        return rows
+            .filter((row) => this.can(action, subject, row))
+            .map((row) => this.filterAllowedFields(action, subject, row, row));
+    }
+}
+exports.AccessGuard = AccessGuard;

package/dist/access/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './guard.js';
+export * from './engine.js';
+export * from './client.js';

package/dist/access/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./guard.js"), exports);
+__exportStar(require("./engine.js"), exports);
+__exportStar(require("./client.js"), exports);

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

@@ -0,0 +1,32 @@
+import React, { ReactNode } from 'react';
+import { AccessGuard } from '../guard.js';
+import { AccessAction, AccessSubject } from '../types.js';
+export interface AccessContextValue<TUser = any> {
+    guard: AccessGuard<TUser> | null;
+    user: TUser | null;
+    can: (action: AccessAction, subject: AccessSubject, record?: any) => boolean;
+    cannot: (action: AccessAction, subject: AccessSubject, record?: any) => boolean;
+    assertCan: (action: AccessAction, subject: AccessSubject, record?: any) => void;
+}
+export interface AccessProviderProps<TUser = any> {
+    guard: AccessGuard<TUser>;
+    children: ReactNode;
+}
+export declare function AccessProvider<TUser = any>({ guard, children, }: AccessProviderProps<TUser>): React.JSX.Element;
+export declare function useAccess<TUser = any>(): AccessContextValue<TUser>;
+export interface CanProps {
+    I: AccessAction;
+    a: AccessSubject;
+    this?: any;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+export declare function Can({ I, a, this: record, fallback, children }: CanProps): React.JSX.Element;
+export interface CannotProps {
+    I: AccessAction;
+    a: AccessSubject;
+    this?: any;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+export declare function Cannot({ I, a, this: record, fallback, children }: CannotProps): React.JSX.Element;

package/dist/access/react/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessProvider = AccessProvider;
+exports.useAccess = useAccess;
+exports.Can = Can;
+exports.Cannot = Cannot;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const AccessContext = (0, react_1.createContext)(null);
+function AccessProvider({ guard, children, }) {
+    const value = (0, react_1.useMemo)(() => {
+        return {
+            guard,
+            user: guard.user,
+            can: (action, subject, record) => guard.can(action, subject, record),
+            cannot: (action, subject, record) => guard.cannot(action, subject, record),
+            assertCan: (action, subject, record) => guard.assertCan(action, subject, record),
+        };
+    }, [guard]);
+    return (0, jsx_runtime_1.jsx)(AccessContext.Provider, { value: value, children: children });
+}
+function useAccess() {
+    const context = (0, react_1.useContext)(AccessContext);
+    if (!context) {
+        throw new Error('useAccess must be used within an <AccessProvider>');
+    }
+    return context;
+}
+function Can({ I, a, this: record, fallback = null, children }) {
+    const { can } = useAccess();
+    if (can(I, a, record)) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
+}
+function Cannot({ I, a, this: record, fallback = null, children }) {
+    const { cannot } = useAccess();
+    if (cannot(I, a, record)) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
+}

package/dist/access/types.d.ts

@@ -0,0 +1,26 @@
+export type AccessAction = 'create' | 'read' | 'update' | 'delete' | 'manage' | (string & {});
+export type AccessSubject = 'all' | (string & {});
+export type AccessPredicate<TRecord = any, TUser = any> = (record?: TRecord, user?: TUser | null) => boolean;
+export interface RuleOptions {
+    fields?: string[];
+    description?: string;
+}
+export interface AccessRule<TUser = any> {
+    inverted: boolean;
+    actions: string[];
+    subjects: string[];
+    predicate?: AccessPredicate<any, TUser>;
+    fields?: string[];
+    description?: string;
+}
+export interface AccessRuleBuilder<TUser = any> {
+    can(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], predicate?: AccessPredicate<any, TUser>): this;
+    can(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], options: RuleOptions, predicate?: AccessPredicate<any, TUser>): this;
+    cannot(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], predicate?: AccessPredicate<any, TUser>): this;
+    cannot(action: AccessAction | AccessAction[], subject: AccessSubject | AccessSubject[], options: RuleOptions, predicate?: AccessPredicate<any, TUser>): this;
+}
+export type AccessPolicyDefinition<TUser = any> = (builder: AccessRuleBuilder<TUser>, user: TUser | null) => void;
+export interface AccessEngine<TUser = any> {
+    createGuard(user: TUser | null): any;
+    for(user: TUser | null): any;
+}

package/dist/access/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/client.d.ts

@@ -7,6 +7,7 @@ import { SchemaManager } from './schema-manager.js';
 import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js';
+import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions, type ImportCsvOptions, type ImportSummary } from '../utils/portability.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -62,6 +63,10 @@ export declare class TransactionalClient {
         includeDeleted?: boolean;
     }): Promise<T[]>;
     findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Alias for findMany().
+     */
+    find<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
     query<T = any>(sql: string, params?: any[]): Promise<T[]>;
     from<T = any>(tableName: string): QueryBuilder<T>;
     get rawTx(): LocalTransaction;
@@ -227,6 +232,32 @@ export declare class LocalFirstClient {
      */
     aggregate(tableName: string, spec: AggregateSpec): Promise<AggregateResult>;
     findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Alias for findMany().
+     */
+    find<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Returns true if client storage has successfully initialized.
+     */
+    get isReady(): boolean;
+    /**
+     * Convenience export of tables to JSON.
+     */
+    exportToJson(tables?: string[], options?: ExportJsonOptions): Promise<string>;
+    /**
+     * Convenience import of tables from JSON.
+     */
+    importFromJson(jsonString: string, options?: ImportJsonOptions): Promise<ImportSummary>;
+    /**
+     * Convenience export of a table to RFC-4180 CSV.
+     */
+    exportToCsv(tableName: string, options?: ExportCsvOptions): Promise<string>;
+    /**
+     * Convenience import of RFC-4180 CSV into a table.
+     */
+    importFromCsv(tableName: string, csvString: string, options?: ImportCsvOptions): Promise<{
+        rowCount: number;
+    }>;
     /**
      * Finds a single record by primary key.
      *

package/dist/core/client.js

@@ -12,6 +12,7 @@ const uuid_js_1 = require("../utils/uuid.js");
 const sql_js_1 = require("../utils/sql.js");
 const query_js_1 = require("./query.js");
 const query_builder_js_1 = require("./query-builder.js");
+const portability_js_1 = require("../utils/portability.js");
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -133,6 +134,12 @@ class TransactionalClient {
         }
         return this.from(tableName).applyOptions(options).execute();
     }
+    /**
+     * Alias for findMany().
+     */
+    async find(tableName, options) {
+        return this.findMany(tableName, options);
+    }
     async query(sql, params = []) {
         return (await this.tx.execute(sql, params));
     }
@@ -715,6 +722,42 @@ class LocalFirstClient {
         }
         return this.from(tableName).applyOptions(options).execute();
     }
+    /**
+     * Alias for findMany().
+     */
+    async find(tableName, options) {
+        return this.findMany(tableName, options);
+    }
+    /**
+     * Returns true if client storage has successfully initialized.
+     */
+    get isReady() {
+        return Boolean(this.initialization);
+    }
+    /**
+     * Convenience export of tables to JSON.
+     */
+    async exportToJson(tables, options) {
+        return (0, portability_js_1.exportTablesToJson)(this, tables, options);
+    }
+    /**
+     * Convenience import of tables from JSON.
+     */
+    async importFromJson(jsonString, options) {
+        return (0, portability_js_1.importTablesFromJson)(this, jsonString, options);
+    }
+    /**
+     * Convenience export of a table to RFC-4180 CSV.
+     */
+    async exportToCsv(tableName, options) {
+        return (0, portability_js_1.exportTableToCsv)(this, tableName, options);
+    }
+    /**
+     * Convenience import of RFC-4180 CSV into a table.
+     */
+    async importFromCsv(tableName, csvString, options) {
+        return (0, portability_js_1.importTableFromCsv)(this, tableName, csvString, options);
+    }
     /**
      * Finds a single record by primary key.
      *

package/dist/core/index.d.ts

@@ -8,6 +8,7 @@ export * from './meta-store.js';
 export * from './table-manager.js';
 export * from './schema-manager.js';
 export * from './query-builder.js';
+export * from './maintenance.js';
 export * from '../reactive/event-emitter.js';
 export * from '../adapters/network/index.js';
 export type { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';

package/dist/core/index.js

@@ -25,6 +25,7 @@ __exportStar(require("./meta-store.js"), exports);
 __exportStar(require("./table-manager.js"), exports);
 __exportStar(require("./schema-manager.js"), exports);
 __exportStar(require("./query-builder.js"), exports);
+__exportStar(require("./maintenance.js"), exports);
 __exportStar(require("../reactive/event-emitter.js"), exports);
 __exportStar(require("../adapters/network/index.js"), exports);
 __exportStar(require("../utils/logger.js"), exports);

package/dist/core/sync-worker.js

@@ -7,6 +7,7 @@ const outbox_store_js_1 = require("./outbox-store.js");
 const meta_store_js_1 = require("./meta-store.js");
 const table_manager_js_1 = require("./table-manager.js");
 const logger_js_1 = require("../utils/logger.js");
+const dynamic_js_1 = require("../utils/dynamic.js");
 const REACT_NATIVE_PKG = ['react', 'native'].join('-');
 /** Maximum outbox records sent per push cycle. */
 const PUSH_BATCH_SIZE = 50;
@@ -236,7 +237,8 @@ class SyncWorker {
             return false;
         // React Native AppState
         try {
-            const { AppState } = require('react-native');
+            const rn = (0, dynamic_js_1.safeDynamicRequire)(REACT_NATIVE_PKG);
+            const AppState = rn?.AppState;
             if (AppState?.currentState && typeof AppState.currentState === 'string') {
                 return Boolean(AppState.currentState.match(/inactive|background/));
             }
@@ -255,7 +257,8 @@ class SyncWorker {
             return;
         // 1. Try React Native AppState
         try {
-            const { AppState } = require('react-native');
+            const rn = (0, dynamic_js_1.safeDynamicRequire)(REACT_NATIVE_PKG);
+            const AppState = rn?.AppState;
             if (AppState && typeof AppState.addEventListener === 'function') {
                 const sub = AppState.addEventListener('change', (state) => {
                     if (state.match(/inactive|background/)) {

package/dist/index.d.ts

@@ -22,3 +22,4 @@ export * from './utils/portability.js';
 export * from './schema/index.js';
 export * from './auth/index.js';
 export * from './backups/index.js';
+export * from './access/index.js';

package/dist/index.js

@@ -37,3 +37,4 @@ __exportStar(require("./utils/portability.js"), exports);
 __exportStar(require("./schema/index.js"), exports);
 __exportStar(require("./auth/index.js"), exports);
 __exportStar(require("./backups/index.js"), exports);
+__exportStar(require("./access/index.js"), exports);

package/dist/react/index.d.ts

@@ -111,6 +111,18 @@ export interface UseMutationsResult<TTable extends string = string> {
  * Universal mutations hook providing memoized, null-safe helpers for database operations.
  */
 export declare function useMutations<TTable extends string = string>(client: LocalFirstClient | null | undefined): UseMutationsResult<TTable>;
+export interface UseDatabaseMaintenanceResult {
+    stats: import('../core/maintenance.js').StorageStats | null;
+    loading: boolean;
+    refreshStats: () => Promise<import('../core/maintenance.js').StorageStats | null>;
+    pruneOutbox: (options?: import('../core/maintenance.js').PruneOutboxOptions) => Promise<number>;
+    vacuum: () => Promise<void>;
+    checkpoint: (mode?: import('../core/maintenance.js').CheckpointMode) => Promise<void>;
+}
+/**
+ * Reactive hook for database maintenance (vacuum, WAL checkpoint, outbox pruning, and storage metrics).
+ */
+export declare function useDatabaseMaintenance(client: LocalFirstClient | null | undefined): UseDatabaseMaintenanceResult;
 export * from './runner.js';
 export * from './status.js';
 export * from './theme.js';

package/dist/react/index.js

@@ -21,6 +21,7 @@ exports.useLiveQueries = useLiveQueries;
 exports.useLiveRow = useLiveRow;
 exports.useLiveInfiniteQuery = useLiveInfiniteQuery;
 exports.useMutations = useMutations;
+exports.useDatabaseMaintenance = useDatabaseMaintenance;
 const react_1 = require("react");
 const runner_js_1 = require("./runner.js");
 function areRowsEqual(a, b) {
@@ -587,6 +588,56 @@ function useMutations(client) {
         transaction: (action) => client ? client.transaction(action) : Promise.resolve(undefined),
     }), [client]);
 }
+/**
+ * Reactive hook for database maintenance (vacuum, WAL checkpoint, outbox pruning, and storage metrics).
+ */
+function useDatabaseMaintenance(client) {
+    const [stats, setStats] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const refreshStats = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        setLoading(true);
+        try {
+            const res = await client.maintenance.getStorageStats();
+            setStats(res);
+            return res;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const pruneOutbox = (0, react_1.useCallback)(async (options) => {
+        if (!client)
+            return 0;
+        const count = await client.maintenance.pruneOutbox(options);
+        await refreshStats();
+        return count;
+    }, [client, refreshStats]);
+    const vacuum = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        await client.maintenance.vacuum();
+        await refreshStats();
+    }, [client, refreshStats]);
+    const checkpoint = (0, react_1.useCallback)(async (mode) => {
+        if (!client)
+            return;
+        await client.maintenance.checkpoint(mode);
+        await refreshStats();
+    }, [client, refreshStats]);
+    return {
+        stats,
+        loading,
+        refreshStats,
+        pruneOutbox,
+        vacuum,
+        checkpoint,
+    };
+}
 __exportStar(require("./runner.js"), exports);
 __exportStar(require("./status.js"), exports);
 __exportStar(require("./theme.js"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -56,6 +56,16 @@
       "import": "./dist/backups/index.js",
       "default": "./dist/backups/index.js"
     },
+    "./portability": {
+      "types": "./dist/utils/portability.d.ts",
+      "import": "./dist/utils/portability.js",
+      "default": "./dist/utils/portability.js"
+    },
+    "./maintenance": {
+      "types": "./dist/core/maintenance.d.ts",
+      "import": "./dist/core/maintenance.js",
+      "default": "./dist/core/maintenance.js"
+    },
     "./expo-sqlite": {
       "types": "./dist/adapters/local/expo-sqlite.d.ts",
       "import": "./dist/adapters/local/expo-sqlite.js",
@@ -90,6 +100,16 @@
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.js",
       "default": "./dist/core/index.js"
+    },
+    "./access": {
+      "types": "./dist/access/index.d.ts",
+      "import": "./dist/access/index.js",
+      "default": "./dist/access/index.js"
+    },
+    "./access/react": {
+      "types": "./dist/access/react/index.d.ts",
+      "import": "./dist/access/react/index.js",
+      "default": "./dist/access/react/index.js"
     }
   },
   "scripts": {