local-lite 0.0.0-stage → 0.0.2

package/dist/utils/logger.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLogger = exports.SyncLogger = void 0;
+exports.formatSupabaseError = formatSupabaseError;
+exports.formatFirestoreError = formatFirestoreError;
+exports.formatConvexError = formatConvexError;
+const LOG_LEVEL_WEIGHTS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+class SyncLogger {
+    level = 'info';
+    customLogger;
+    enabled = true;
+    constructor(config) {
+        if (typeof config === 'boolean') {
+            this.enabled = config;
+        }
+        else if (config) {
+            if (config.enabled !== undefined)
+                this.enabled = config.enabled;
+            if (config.level)
+                this.level = config.level;
+            if (config.customLogger)
+                this.customLogger = config.customLogger;
+        }
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    setCustomLogger(logger) {
+        this.customLogger = logger;
+    }
+    shouldLog(level) {
+        if (!this.enabled || this.level === 'silent')
+            return false;
+        return LOG_LEVEL_WEIGHTS[level] >= LOG_LEVEL_WEIGHTS[this.level];
+    }
+    debug(message, ...args) {
+        if (!this.shouldLog('debug'))
+            return;
+        if (this.customLogger?.debug) {
+            this.customLogger.debug(message, ...args);
+        }
+        else {
+            console.debug(`[local-lite] ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (!this.shouldLog('info'))
+            return;
+        if (this.customLogger?.info) {
+            this.customLogger.info(message, ...args);
+        }
+        else {
+            console.info(`[local-lite] ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (!this.shouldLog('warn'))
+            return;
+        if (this.customLogger?.warn) {
+            this.customLogger.warn(message, ...args);
+        }
+        else {
+            console.warn(`[local-lite] ${message}`, ...args);
+        }
+    }
+    error(message, ...args) {
+        if (!this.shouldLog('error'))
+            return;
+        if (this.customLogger?.error) {
+            this.customLogger.error(message, ...args);
+        }
+        else {
+            console.error(`[local-lite] ${message}`, ...args);
+        }
+    }
+}
+exports.SyncLogger = SyncLogger;
+/**
+ * Global default logger instance.
+ */
+exports.defaultLogger = new SyncLogger();
+/**
+ * Translates PostgreSQL / Supabase PostgREST error codes into actionable, human-readable explanations.
+ */
+function formatSupabaseError(error, context = {}) {
+    if (!error)
+        return 'Unknown Supabase error';
+    const table = context.table ? `"${context.table}"` : 'table';
+    const op = context.operation ? ` (${context.operation})` : '';
+    const code = String(error.code || error.status || '').trim();
+    const rawMsg = error.message || error.details || String(error);
+    // PostgreSQL RLS 42501 (insufficient_privilege)
+    if (code === '42501' || rawMsg.toLowerCase().includes('row-level security')) {
+        return `🔒 RLS Permission Denied on ${table}${op}: Row-Level Security blocked this mutation. Check that the user is authenticated and matching RLS policies exist on Postgres.`;
+    }
+    // PostgreSQL 23502 (not_null_violation)
+    if (code === '23502') {
+        const hint = error.details || rawMsg;
+        return `⚠️ Missing Required Column on ${table}${op}: NOT NULL constraint violated. (${hint})`;
+    }
+    // PostgreSQL 23505 (unique_violation)
+    if (code === '23505') {
+        const hint = error.details || rawMsg;
+        return `⚠️ Duplicate Key on ${table}${op}: Unique constraint violated. (${hint})`;
+    }
+    // PostgreSQL 23503 (foreign_key_violation)
+    if (code === '23503') {
+        const hint = error.details || rawMsg;
+        return `⚠️ Foreign Key Missing on ${table}${op}: Referenced relation does not exist. (${hint})`;
+    }
+    // Supabase Auth / JWT expired (PGRST301, JWT expired)
+    if (code === 'PGRST301' || rawMsg.toLowerCase().includes('jwt')) {
+        return `🔑 Session Expired on ${table}${op}: Supabase auth token is invalid or expired.`;
+    }
+    // Network / Offline errors
+    if (rawMsg.toLowerCase().includes('fetch failed') ||
+        rawMsg.toLowerCase().includes('enotfound') ||
+        rawMsg.toLowerCase().includes('network')) {
+        return `📡 Network Offline: Failed to reach Supabase backend. Mutations safely preserved in local SQLite outbox.`;
+    }
+    return `❌ Supabase error on ${table}${op} [code: ${code || 'N/A'}]: ${rawMsg}`;
+}
+/**
+ * Translates Firestore error codes into human-readable explanations.
+ */
+function formatFirestoreError(error, context = {}) {
+    if (!error)
+        return 'Unknown Firestore error';
+    const collection = context.collection ? `"${context.collection}"` : 'collection';
+    const op = context.operation ? ` (${context.operation})` : '';
+    const code = String(error.code || '').toLowerCase();
+    const rawMsg = error.message || String(error);
+    if (code.includes('permission-denied') || rawMsg.toLowerCase().includes('insufficient permissions')) {
+        return `🔒 Permission Denied on collection ${collection}${op}: Check your Firestore Security Rules.`;
+    }
+    if (code.includes('unauthenticated')) {
+        return `🔑 Unauthenticated on collection ${collection}${op}: User must be signed into Firebase Auth.`;
+    }
+    if (code.includes('unavailable') || rawMsg.toLowerCase().includes('network')) {
+        return `📡 Firestore Offline: Backend unreachable. Mutations preserved in local SQLite outbox.`;
+    }
+    return `❌ Firestore error on ${collection}${op}: ${rawMsg}`;
+}
+/**
+ * Translates Convex error codes into human-readable explanations.
+ */
+function formatConvexError(error, context = {}) {
+    if (!error)
+        return 'Unknown Convex error';
+    const table = context.table ? `"${context.table}"` : 'table';
+    const op = context.operation ? ` (${context.operation})` : '';
+    const rawMsg = error.message || String(error);
+    if (rawMsg.toLowerCase().includes('unauthorized') || rawMsg.toLowerCase().includes('unauthenticated')) {
+        return `🔒 Convex Permission Denied on ${table}${op}: Request unauthorized.`;
+    }
+    if (rawMsg.toLowerCase().includes('network') || rawMsg.toLowerCase().includes('failed to fetch')) {
+        return `📡 Convex Offline: Server unreachable. Mutations preserved in local SQLite outbox.`;
+    }
+    return `❌ Convex error on ${table}${op}: ${rawMsg}`;
+}

package/dist/utils/sql.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Safely escape a SQL identifier (table name or column name) with double quotes.
+ */
+export declare function escapeIdentifier(identifier: string): string;

package/dist/utils/sql.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeIdentifier = escapeIdentifier;
+/**
+ * Safely escape a SQL identifier (table name or column name) with double quotes.
+ */
+function escapeIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}

package/dist/utils/uuid.d.ts

@@ -0,0 +1,7 @@
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Generates an RFC4122 v4 compliant UUID.
+ * Uses native crypto.randomUUID() when supported, with uuid.v4 fallback.
+ */
+export declare function generateUUID(): string;
+export { uuidv4 };

package/dist/utils/uuid.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidv4 = void 0;
+exports.generateUUID = generateUUID;
+const uuid_1 = require("uuid");
+Object.defineProperty(exports, "uuidv4", { enumerable: true, get: function () { return uuid_1.v4; } });
+/**
+ * Generates an RFC4122 v4 compliant UUID.
+ * Uses native crypto.randomUUID() when supported, with uuid.v4 fallback.
+ */
+function generateUUID() {
+    try {
+        if (typeof globalThis !== 'undefined' &&
+            globalThis.crypto &&
+            typeof globalThis.crypto.randomUUID === 'function') {
+            return globalThis.crypto.randomUUID();
+        }
+        return (0, uuid_1.v4)();
+    }
+    catch {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,133 @@
 {
   "name": "local-lite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "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",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
+    },
+    "./supabase": {
+      "types": "./dist/adapters/remote/supabase.d.ts",
+      "import": "./dist/adapters/remote/supabase.js",
+      "default": "./dist/adapters/remote/supabase.js"
+    },
+    "./convex": {
+      "types": "./dist/adapters/remote/convex.d.ts",
+      "import": "./dist/adapters/remote/convex.js",
+      "default": "./dist/adapters/remote/convex.js"
+    },
+    "./firebase": {
+      "types": "./dist/adapters/remote/firestore.d.ts",
+      "import": "./dist/adapters/remote/firestore.js",
+      "default": "./dist/adapters/remote/firestore.js"
+    },
+    "./expo-sqlite": {
+      "types": "./dist/adapters/local/expo-sqlite.d.ts",
+      "import": "./dist/adapters/local/expo-sqlite.js",
+      "default": "./dist/adapters/local/expo-sqlite.js"
+    },
+    "./op-sqlite": {
+      "types": "./dist/adapters/local/op-sqlite.d.ts",
+      "import": "./dist/adapters/local/op-sqlite.js",
+      "default": "./dist/adapters/local/op-sqlite.js"
+    },
+    "./better-sqlite3": {
+      "types": "./dist/adapters/local/better-sqlite3.d.ts",
+      "import": "./dist/adapters/local/better-sqlite3.js",
+      "default": "./dist/adapters/local/better-sqlite3.js"
+    },
+    "./libsql": {
+      "types": "./dist/adapters/local/libsql.d.ts",
+      "import": "./dist/adapters/local/libsql.js",
+      "default": "./dist/adapters/local/libsql.js"
+    },
+    "./sql-js": {
+      "types": "./dist/adapters/local/sql-js.d.ts",
+      "import": "./dist/adapters/local/sql-js.js",
+      "default": "./dist/adapters/local/sql-js.js"
+    },
+    "./node-sqlite": {
+      "types": "./dist/adapters/local/node-sqlite.d.ts",
+      "import": "./dist/adapters/local/node-sqlite.js",
+      "default": "./dist/adapters/local/node-sqlite.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@libsql/client": "^0.6.0",
+    "@op-engineering/op-sqlite": "^0.1.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "better-sqlite3": "^8.0.0",
+    "convex": ">=1.0.0",
+    "expo-sqlite": "^57.0.0",
+    "firebase": ">=9.0.0",
+    "react": ">=18.0.0",
+    "sql.js": "^1.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "convex": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    },
+    "expo-sqlite": {
+      "optional": true
+    },
+    "@op-engineering/op-sqlite": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    },
+    "sql.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.117.3",
+    "@types/react": "^19.3.0",
+    "@types/uuid": "^11.0.0",
+    "expo-sqlite": "^57.0.4",
+    "react": "^19.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.4"
+  },
+  "dependencies": {
+    "uuid": "^14.0.3"
+  }
+}