locallytics 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,56 @@
+# locallytics
+
+`locallytics` is a lightweight, framework-agnostic analytics runtime.
+This release currently supports SQLite.
+
+## Install
+
+```npm
+npm install locallytics better-sqlite3
+```
+
+## Quickstart
+
+Create one shared Locallytics instance.
+
+```ts
+import { createLocallytics } from "locallytics";
+import Database from "better-sqlite3";
+
+export const locallytics = createLocallytics({
+  database: new Database("database.sqlite"),
+  sessionTracking: true,
+});
+```
+
+Track custom events.
+
+```ts
+await locallytics.track("button_click", { button: "cta" });
+```
+
+Read stored events.
+
+```ts
+const events = await locallytics.listEvents({ limit: 25 });
+```
+
+## API
+
+- `createLocallytics(config)`
+- `locallytics.track(type, metadata?)`
+- `locallytics.trackPageView(route?)`
+- `locallytics.listEvents(options?)`
+- `locallytics.setUserId(userId)`
+- `locallytics.getUserId()`
+- `locallytics.getSessionId()`
+
+## CLI
+
+Use `@locallytics/cli` to generate and run migrations:
+
+```npm
+npm install -D @locallytics/cli
+npx locallytics generate
+npx locallytics migrate
+```

package/dist/adapters/custom.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseAdapter } from "../types";
+export declare function createCustomAdapter(adapter: DatabaseAdapter): DatabaseAdapter;
+//# sourceMappingURL=custom.d.ts.map

package/dist/adapters/custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../src/adapters/custom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAE7E"}

package/dist/adapters/sqlite.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseAdapter, SqliteDatabase } from "../types";
+export declare function createSqliteAdapter(database: SqliteDatabase): DatabaseAdapter;
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/adapters/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/sqlite.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EAIf,cAAc,EACf,MAAM,UAAU,CAAC;AAmDlB,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,eAAe,CAkF7E"}

package/dist/create-locallytics.d.ts

@@ -0,0 +1,3 @@
+import type { Locallytics, LocallyticsConfig } from "./types";
+export declare function createLocallytics(config: LocallyticsConfig): Locallytics;
+//# sourceMappingURL=create-locallytics.d.ts.map

package/dist/create-locallytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-locallytics.d.ts","sourceRoot":"","sources":["../src/create-locallytics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,WAAW,EACX,iBAAiB,EAKlB,MAAM,SAAS,CAAC;AA8DjB,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CA4DxE"}

package/dist/index.d.ts

@@ -1,59 +1,4 @@
-/**
-* Locallytics - Analytics built around a database-first API.
-* @packageDocumentation
-*/
-type LocallyticsEvent = {
-	id?: string | number;
-	type: string;
-	timestamp: number;
-	sessionId?: string;
-	userId?: string;
-	metadata?: Record<string, unknown>;
-};
-interface DatabaseAdapter {
-	initialize?(): Promise<void> | void;
-	insertEvent(event: Omit<LocallyticsEvent, "id">): Promise<LocallyticsEvent>;
-	findEvents(): Promise<LocallyticsEvent[]>;
-}
-type PostgresLikeDatabase = {
-	query: (sql: string, params?: unknown[]) => Promise<{
-		rows: Record<string, unknown>[];
-	}>;
-};
-type MysqlLikeDatabase = {
-	execute: (sql: string, params?: unknown[]) => Promise<[unknown, unknown]>;
-};
-type SqliteLikeStatement = {
-	run: (...params: unknown[]) => {
-		lastInsertRowid?: number | bigint;
-	};
-	all: (...params: unknown[]) => Record<string, unknown>[];
-	get?: (...params: unknown[]) => Record<string, unknown> | undefined;
-};
-type SqliteLikeDatabase = {
-	prepare: (sql: string) => SqliteLikeStatement;
-};
-type SupportedDatabase = DatabaseAdapter | PostgresLikeDatabase | MysqlLikeDatabase | SqliteLikeDatabase;
-type LocallyticsConfig = {
-	database: SupportedDatabase;
-	sessionTracking?: boolean;
-	userId?: string;
-};
-type ClientQueryResult = {
-	events: LocallyticsEvent[];
-	loading: boolean;
-	error: Error | null;
-	refresh: () => Promise<LocallyticsEvent[]>;
-};
-type QueryResult = ClientQueryResult & PromiseLike<LocallyticsEvent[]>;
-interface Locallytics {
-	track(type: string, metadata?: Record<string, unknown>): Promise<LocallyticsEvent>;
-	trackPageView(route?: string): Promise<LocallyticsEvent>;
-	query(): QueryResult;
-	setUserId(userId: string | undefined): void;
-	getUserId(): string | undefined;
-	getSessionId(): string | undefined;
-	subscribe(listener: () => void): () => void;
-}
-declare function createLocallytics(config: LocallyticsConfig): Locallytics;
-export { createLocallytics, SupportedDatabase, SqliteLikeStatement, SqliteLikeDatabase, QueryResult, PostgresLikeDatabase, MysqlLikeDatabase, LocallyticsEvent, LocallyticsConfig, Locallytics, DatabaseAdapter, ClientQueryResult };
+export { createLocallytics } from "./create-locallytics";
+export { EVENTS_TABLE_NAME, SQLITE_CREATE_EVENTS_TABLE_SQL } from "./sql";
+export type { DatabaseAdapter, EventMetadata, ListEventsOptions, Locallytics, LocallyticsConfig, LocallyticsEvent, LocallyticsEventInput, SqliteDatabase, SqliteStatement, SupportedDatabase, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,8BAA8B,EAAE,MAAM,OAAO,CAAC;AAC1E,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,41 +1,9 @@
-var import_node_module = require("node:module");
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-
-// src/index.ts
-var exports_src = {};
-__export(exports_src, {
-  createLocallytics: () => createLocallytics
-});
-module.exports = __toCommonJS(exports_src);
-function toError(error) {
-  return error instanceof Error ? error : new Error(String(error));
+// src/adapters/custom.ts
+function createCustomAdapter(adapter) {
+  return adapter;
 }
+
+// src/normalize.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -46,15 +14,21 @@ function parseMetadata(value) {
   if (isRecord(value)) {
     return value;
   }
-  if (typeof value === "string") {
-    try {
-      const parsed = JSON.parse(value);
-      return isRecord(parsed) ? parsed : undefined;
-    } catch {
-      return;
-    }
+  if (typeof value !== "string") {
+    return;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return;
   }
-  return;
+}
+function stringifyMetadata(metadata) {
+  if (!metadata) {
+    return null;
+  }
+  return JSON.stringify(metadata);
 }
 function normalizeEventRow(row) {
   return {
@@ -66,123 +40,54 @@ function normalizeEventRow(row) {
     metadata: parseMetadata(row.metadata)
   };
 }
-function stringifyMetadata(metadata) {
-  return metadata ? JSON.stringify(metadata) : null;
-}
-function isDatabaseAdapter(database) {
-  return "insertEvent" in database && typeof database.insertEvent === "function" && "findEvents" in database && typeof database.findEvents === "function";
-}
-function isPostgresLikeDatabase(database) {
-  return "query" in database && typeof database.query === "function";
-}
-function isMysqlLikeDatabase(database) {
-  return "execute" in database && typeof database.execute === "function";
-}
-function isSqliteLikeDatabase(database) {
-  return "prepare" in database && typeof database.prepare === "function";
+
+// src/sql.ts
+var EVENTS_TABLE_NAME = "locallytics_events";
+var SQLITE_CREATE_EVENTS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS locallytics_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  type TEXT NOT NULL,
+  timestamp INTEGER NOT NULL,
+  session_id TEXT,
+  user_id TEXT,
+  metadata TEXT
+);
+`;
+
+// src/adapters/sqlite.ts
+function toRow(value) {
+  if (typeof value === "object" && value !== null) {
+    return value;
+  }
+  return {};
 }
-function createPostgresAdapter(database) {
-  let initialized = false;
-  async function ensureInitialized() {
-    if (initialized) {
-      return;
-    }
-    await database.query(`
-      CREATE TABLE IF NOT EXISTS locallytics_events (
-        id BIGSERIAL PRIMARY KEY,
-        type TEXT NOT NULL,
-        timestamp BIGINT NOT NULL,
-        session_id TEXT,
-        user_id TEXT,
-        metadata JSONB
-      )
-    `);
-    initialized = true;
+function toInsertId(value) {
+  if (!value || typeof value !== "object") {
+    return;
   }
-  return {
-    initialize: ensureInitialized,
-    async insertEvent(event) {
-      await ensureInitialized();
-      const result = await database.query(`
-          INSERT INTO locallytics_events (type, timestamp, session_id, user_id, metadata)
-          VALUES ($1, $2, $3, $4, $5::jsonb)
-          RETURNING id, type, timestamp, session_id, user_id, metadata
-        `, [
-        event.type,
-        event.timestamp,
-        event.sessionId ?? null,
-        event.userId ?? null,
-        stringifyMetadata(event.metadata)
-      ]);
-      const first = result.rows[0];
-      return first ? normalizeEventRow(first) : { ...event };
-    },
-    async findEvents() {
-      await ensureInitialized();
-      const result = await database.query(`
-          SELECT id, type, timestamp, session_id, user_id, metadata
-          FROM locallytics_events
-          ORDER BY timestamp DESC
-        `);
-      return result.rows.map(normalizeEventRow);
-    }
-  };
+  const row = value;
+  const id = row.lastInsertRowid;
+  if (typeof id === "number") {
+    return id;
+  }
+  if (typeof id === "bigint") {
+    return Number(id);
+  }
+  if (typeof id === "string" && id.length > 0) {
+    return Number(id);
+  }
+  return;
 }
-function createMysqlAdapter(database) {
-  let initialized = false;
-  async function ensureInitialized() {
-    if (initialized) {
-      return;
-    }
-    await database.execute(`
-      CREATE TABLE IF NOT EXISTS locallytics_events (
-        id BIGINT AUTO_INCREMENT PRIMARY KEY,
-        type VARCHAR(255) NOT NULL,
-        timestamp BIGINT NOT NULL,
-        session_id VARCHAR(255),
-        user_id VARCHAR(255),
-        metadata JSON
-      )
-    `);
-    initialized = true;
+function toSafeLimit(limit) {
+  if (limit == null) {
+    return;
   }
-  return {
-    initialize: ensureInitialized,
-    async insertEvent(event) {
-      await ensureInitialized();
-      const [insertResult] = await database.execute(`
-          INSERT INTO locallytics_events (type, timestamp, session_id, user_id, metadata)
-          VALUES (?, ?, ?, ?, ?)
-        `, [
-        event.type,
-        event.timestamp,
-        event.sessionId ?? null,
-        event.userId ?? null,
-        stringifyMetadata(event.metadata)
-      ]);
-      const insertId = Number(insertResult.insertId ?? 0);
-      if (!insertId) {
-        return { ...event };
-      }
-      const [rows] = await database.execute(`
-          SELECT id, type, timestamp, session_id, user_id, metadata
-          FROM locallytics_events
-          WHERE id = ?
-          LIMIT 1
-        `, [insertId]);
-      const first = rows[0];
-      return first ? normalizeEventRow(first) : { ...event, id: insertId };
-    },
-    async findEvents() {
-      await ensureInitialized();
-      const [rows] = await database.execute(`
-          SELECT id, type, timestamp, session_id, user_id, metadata
-          FROM locallytics_events
-          ORDER BY timestamp DESC
-        `);
-      return rows.map(normalizeEventRow);
-    }
-  };
+  const normalized = Math.floor(limit);
+  return normalized > 0 ? normalized : 1;
+}
+function toSqlResultRows(database, sql, params) {
+  const statement = database.prepare(sql);
+  return statement.all(...params).map((row) => normalizeEventRow(toRow(row)));
 }
 function createSqliteAdapter(database) {
   let initialized = false;
@@ -190,178 +95,160 @@ function createSqliteAdapter(database) {
     if (initialized) {
       return;
     }
-    database.prepare(`
-      CREATE TABLE IF NOT EXISTS locallytics_events (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        type TEXT NOT NULL,
-        timestamp INTEGER NOT NULL,
-        session_id TEXT,
-        user_id TEXT,
-        metadata TEXT
-      )
-    `).run();
+    database.prepare(SQLITE_CREATE_EVENTS_TABLE_SQL).run();
     initialized = true;
   }
   return {
     initialize: ensureInitialized,
     async insertEvent(event) {
       ensureInitialized();
-      const insert = database.prepare(`
-          INSERT INTO locallytics_events (type, timestamp, session_id, user_id, metadata)
-          VALUES (?, ?, ?, ?, ?)
-        `);
-      const result = insert.run(event.type, event.timestamp, event.sessionId ?? null, event.userId ?? null, stringifyMetadata(event.metadata));
-      const insertId = Number(result.lastInsertRowid ?? 0);
+      const result = database.prepare(`
+            INSERT INTO locallytics_events (type, timestamp, session_id, user_id, metadata)
+            VALUES (?, ?, ?, ?, ?)
+          `).run(event.type, event.timestamp, event.sessionId ?? null, event.userId ?? null, stringifyMetadata(event.metadata));
+      const id = toInsertId(result);
+      if (id == null) {
+        return { ...event };
+      }
       const select = database.prepare(`
           SELECT id, type, timestamp, session_id, user_id, metadata
           FROM locallytics_events
           WHERE id = ?
           LIMIT 1
         `);
-      const row = select.get ? select.get(insertId) : select.all(insertId)[0];
-      return row ? normalizeEventRow(row) : { ...event, id: insertId };
+      const row = select.get ? select.get(id) : select.all(id)[0];
+      return row ? normalizeEventRow(toRow(row)) : { ...event, id };
     },
-    async findEvents() {
+    async listEvents(options) {
       ensureInitialized();
-      const rows = database.prepare(`
-            SELECT id, type, timestamp, session_id, user_id, metadata
-            FROM locallytics_events
-            ORDER BY timestamp DESC
-          `).all();
-      return rows.map(normalizeEventRow);
+      const params = [];
+      const where = [];
+      if (options?.type) {
+        where.push("type = ?");
+        params.push(options.type);
+      }
+      let sql = `
+        SELECT id, type, timestamp, session_id, user_id, metadata
+        FROM locallytics_events
+      `;
+      if (where.length > 0) {
+        sql += ` WHERE ${where.join(" AND ")}`;
+      }
+      sql += " ORDER BY timestamp DESC, id DESC";
+      const limit = toSafeLimit(options?.limit);
+      if (limit) {
+        sql += " LIMIT ?";
+        params.push(limit);
+      }
+      return toSqlResultRows(database, sql, params);
     }
   };
 }
-function createDatabaseAdapter(database) {
-  if (isDatabaseAdapter(database)) {
-    return database;
-  }
-  if (isPostgresLikeDatabase(database)) {
-    return createPostgresAdapter(database);
+
+// src/session.ts
+function randomSuffix() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
   }
-  if (isMysqlLikeDatabase(database)) {
-    return createMysqlAdapter(database);
+  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function createSessionManager(sessionTracking) {
+  let sessionId;
+  return {
+    getSessionId() {
+      if (!sessionTracking) {
+        return;
+      }
+      if (!sessionId) {
+        sessionId = `ltx_${randomSuffix()}`;
+      }
+      return sessionId;
+    }
+  };
+}
+
+// src/create-locallytics.ts
+function isDatabaseAdapter(database) {
+  return typeof database === "object" && database !== null && "insertEvent" in database && typeof database.insertEvent === "function" && "listEvents" in database && typeof database.listEvents === "function";
+}
+function isSqliteDatabase(database) {
+  return typeof database === "object" && database !== null && "prepare" in database && typeof database.prepare === "function";
+}
+function toDatabaseAdapter(database) {
+  if (isDatabaseAdapter(database)) {
+    return createCustomAdapter(database);
   }
-  if (isSqliteLikeDatabase(database)) {
+  if (isSqliteDatabase(database)) {
     return createSqliteAdapter(database);
   }
-  throw new Error("Unsupported database input. Use a pg Pool, mysql2 pool, better-sqlite3 Database, or a DatabaseAdapter.");
+  throw new Error("Unsupported database input. Pass a better-sqlite3-style database or a custom adapter.");
 }
-function createSessionId() {
-  return `session_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+function normalizeEventType(type) {
+  const normalized = type.trim();
+  if (!normalized) {
+    throw new Error("Event type is required.");
+  }
+  return normalized;
+}
+function resolvePageViewRoute(route) {
+  if (route) {
+    return route;
+  }
+  if (typeof location === "undefined") {
+    return "/";
+  }
+  return `${location.pathname}${location.search}`;
 }
 function createLocallytics(config) {
-  const adapter = createDatabaseAdapter(config.database);
-  const listeners = new Set;
-  const isBrowser = typeof window !== "undefined";
+  const adapter = toDatabaseAdapter(config.database);
+  const sessionManager = createSessionManager(Boolean(config.sessionTracking));
+  let initialized = false;
   let userId = config.userId;
-  let currentSessionId;
-  const queryState = {
-    events: [],
-    loading: false,
-    error: null,
-    loaded: false,
-    pending: undefined
-  };
-  function notify() {
-    for (const listener of listeners) {
-      listener();
-    }
-  }
-  function getSessionId() {
-    if (!config.sessionTracking) {
+  async function ensureInitialized() {
+    if (initialized) {
       return;
     }
-    if (!currentSessionId) {
-      currentSessionId = createSessionId();
-    }
-    return currentSessionId;
-  }
-  async function runQuery(force = false) {
-    if (!force && queryState.pending) {
-      return queryState.pending;
-    }
-    if (!force && isBrowser && queryState.loaded) {
-      return queryState.events;
-    }
-    queryState.loading = true;
-    queryState.error = null;
-    notify();
-    const pending = (async () => {
-      if (adapter.initialize) {
-        await adapter.initialize();
-      }
-      const events = await adapter.findEvents();
-      queryState.events = events;
-      queryState.loaded = true;
-      return events;
-    })().catch((error) => {
-      const normalized = toError(error);
-      queryState.error = normalized;
-      throw normalized;
-    }).finally(() => {
-      queryState.loading = false;
-      queryState.pending = undefined;
-      notify();
-    });
-    queryState.pending = pending;
-    return pending;
-  }
-  async function track(type, metadata) {
     if (adapter.initialize) {
       await adapter.initialize();
     }
-    const event = {
-      type,
+    initialized = true;
+  }
+  async function track(type, metadata) {
+    await ensureInitialized();
+    return adapter.insertEvent({
+      type: normalizeEventType(type),
       timestamp: Date.now(),
-      sessionId: getSessionId(),
+      sessionId: sessionManager.getSessionId(),
       userId,
       metadata
-    };
-    const saved = await adapter.insertEvent(event);
-    if (isBrowser && queryState.loaded) {
-      queryState.events = [saved, ...queryState.events];
-      notify();
-    }
-    return saved;
+    });
   }
-  function createQueryResult(promise) {
-    return {
-      get events() {
-        return queryState.events;
-      },
-      get loading() {
-        return queryState.loading;
-      },
-      get error() {
-        return queryState.error;
-      },
-      refresh: () => runQuery(true),
-      then: promise.then.bind(promise)
-    };
+  async function listEvents(options) {
+    await ensureInitialized();
+    return adapter.listEvents(options);
   }
   return {
     track,
     async trackPageView(route) {
-      const resolvedRoute = route ?? (typeof location !== "undefined" ? `${location.pathname}${location.search}` : "/");
-      return track("page_view", { route: resolvedRoute });
-    },
-    query() {
-      const promise = runQuery(!isBrowser);
-      return createQueryResult(promise);
+      return track("page_view", { route: resolvePageViewRoute(route) });
     },
+    listEvents,
     setUserId(nextUserId) {
       userId = nextUserId;
     },
     getUserId() {
       return userId;
     },
-    getSessionId,
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
+    getSessionId() {
+      return sessionManager.getSessionId();
     }
   };
 }
+export {
+  createLocallytics,
+  SQLITE_CREATE_EVENTS_TABLE_SQL,
+  EVENTS_TABLE_NAME
+};
+
+//# debugId=8CAF93D1E8D8A8E664756E2164756E21
+//# sourceMappingURL=index.js.map