@hasna/events 0.1.13 → 0.1.14

package/dist/storage.js

@@ -1,11 +1,15 @@
 // @bun
 // src/storage.ts
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
+import { Buffer } from "buffer";
 import { existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 var HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+var LOCAL_JSON_EVENT_CURSOR_PREFIX = "local-json-v1:";
+var DEFAULT_EVENT_PAGE_LIMIT = 100;
+var MAX_EVENT_PAGE_LIMIT = 1000;
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
@@ -19,11 +23,13 @@ function getActiveEventsDirEnv() {
 
 class JsonEventsStore {
   dataDir;
+  runtime;
   channelsPath;
   eventsPath;
   deliveriesPath;
   constructor(dataDir = getEventsDataDir()) {
     this.dataDir = dataDir;
+    this.runtime = localJsonRuntime(dataDir);
     this.channelsPath = join(dataDir, "channels.json");
     this.eventsPath = join(dataDir, "events.json");
     this.deliveriesPath = join(dataDir, "deliveries.json");
@@ -71,13 +77,58 @@ class JsonEventsStore {
     await this.writeJson(this.eventsPath, events);
     return event;
   }
-  async listEvents() {
+  async appendEventOnce(event, options = {}) {
     await this.init();
-    return this.readJson(this.eventsPath, []);
+    const events = await this.readJson(this.eventsPath, []);
+    const dedupe = options.dedupe !== false;
+    if (dedupe) {
+      const existing = findEventByIdentity(events, { id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    events.push(event);
+    await this.writeJson(this.eventsPath, events);
+    return {
+      event,
+      stored: true,
+      deduped: false,
+      identity: { id: event.id, dedupeKey: event.dedupeKey }
+    };
+  }
+  async listEvents(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    return queryEvents(events, options);
+  }
+  async listEventsPage(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    const queried = queryEvents(events, {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = queried.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < queried.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async findEventByIdentity(identity) {
     const events = await this.listEvents();
-    return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+    return findEventByIdentity(events, identity);
   }
   async appendDelivery(result) {
     await this.init();
@@ -128,6 +179,83 @@ class JsonEventsStore {
     });
   }
 }
+function localJsonRuntime(dataDir = getEventsDataDir()) {
+  return {
+    mode: "local-files",
+    name: "json-events-store",
+    remote: false,
+    localFiles: true,
+    localSqlite: false,
+    postgres: false,
+    s3: false,
+    aws: false,
+    durable: true,
+    idempotency: "best-effort-local",
+    replayCursors: true,
+    description: `Local JSON files in ${dataDir}; no SQLite, Postgres, S3, or AWS runtime is configured by this store.`
+  };
+}
+function encodeLocalJsonEventCursor(offset, options = {}) {
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid event cursor offset: ${offset}`);
+  const payload = {
+    offset,
+    eventId: options.eventId,
+    source: options.source,
+    type: options.type
+  };
+  return `${LOCAL_JSON_EVENT_CURSOR_PREFIX}${Buffer.from(JSON.stringify(payload), "utf-8").toString("base64url")}`;
+}
+function decodeLocalJsonEventCursor(cursor, options = {}) {
+  if (!cursor)
+    return 0;
+  if (!cursor.startsWith(LOCAL_JSON_EVENT_CURSOR_PREFIX))
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  const rawPayload = cursor.slice(LOCAL_JSON_EVENT_CURSOR_PREFIX.length);
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(rawPayload, "base64url").toString("utf-8"));
+  } catch {
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  }
+  const offset = payload.offset;
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  assertCursorFilter("eventId", payload.eventId, options.eventId);
+  assertCursorFilter("source", payload.source, options.source);
+  assertCursorFilter("type", payload.type, options.type);
+  return offset;
+}
+function normalizeEventPageLimit(limit) {
+  if (limit === undefined)
+    return DEFAULT_EVENT_PAGE_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1)
+    throw new Error(`Event page limit must be a positive integer, got ${limit}`);
+  return Math.min(limit, MAX_EVENT_PAGE_LIMIT);
+}
+function queryEvents(events, options) {
+  let rows = events;
+  if (options.eventId)
+    rows = rows.filter((event) => event.id === options.eventId);
+  if (options.source)
+    rows = rows.filter((event) => event.source === options.source);
+  if (options.type)
+    rows = rows.filter((event) => event.type === options.type);
+  if (options.cursor) {
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    rows = rows.slice(offset);
+  }
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
+}
+function assertCursorFilter(name, cursorValue, optionValue) {
+  if (cursorValue !== optionValue)
+    throw new Error(`Local JSON event cursor ${name} filter mismatch`);
+}
+function findEventByIdentity(events, identity) {
+  return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+}
 async function getEventsStatus(dataDir) {
   const store = new JsonEventsStore(dataDir);
   await store.init();
@@ -144,6 +272,7 @@ async function getEventsStatus(dataDir) {
     service: "events",
     schemaVersion: "1.0",
     dataDir: store.dataDir,
+    storage: store.runtime,
     env: {
       primary: HASNA_EVENTS_DIR_ENV,
       fallback: HASNA_EVENTS_HOME_ENV,
@@ -175,10 +304,17 @@ function statusFile(dataDir, fileName, records) {
   return { path, exists: existsSync(path), records };
 }
 export {
+  normalizeEventPageLimit,
+  localJsonRuntime,
   getEventsStatus,
   getEventsDataDir,
   getActiveEventsDirEnv,
+  encodeLocalJsonEventCursor,
+  decodeLocalJsonEventCursor,
+  MAX_EVENT_PAGE_LIMIT,
+  LOCAL_JSON_EVENT_CURSOR_PREFIX,
   JsonEventsStore,
   HASNA_EVENTS_HOME_ENV,
-  HASNA_EVENTS_DIR_ENV
+  HASNA_EVENTS_DIR_ENV,
+  DEFAULT_EVENT_PAGE_LIMIT
 };

package/dist/types.d.ts

@@ -105,13 +105,50 @@ export interface EmitOptions {
     deliver?: boolean;
     dedupe?: boolean;
     redactSensitiveData?: boolean;
-}
-export interface ReplayOptions {
+    /**
+     * Per-emit override for the opt-in catalog validator hook. When true the
+     * event is validated against the client's `EventTypeCatalog` before it is
+     * stored or delivered (types not registered in the catalog always pass);
+     * when false validation is skipped even if the client enabled
+     * `validateCatalogTypes`. Defaults to the client-level setting (off).
+     */
+    validate?: boolean;
+}
+export interface EventPageOptions {
     eventId?: string;
     source?: string;
     type?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface EventPage {
+    events: EventEnvelope[];
+    cursor?: string;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export interface EventAppendOptions {
+    dedupe?: boolean;
+}
+export interface EventAppendResult<TData extends EventData = EventData> {
+    event: EventEnvelope<TData>;
+    stored: boolean;
+    deduped: boolean;
+    identity: {
+        id: string;
+        dedupeKey?: string;
+    };
+}
+export interface ReplayOptions extends EventPageOptions {
     dryRun?: boolean;
 }
+export interface ReplayResult {
+    events: EventEnvelope[];
+    deliveries: DeliveryResult[];
+    cursor?: string;
+    nextCursor?: string;
+    hasMore: boolean;
+}
 export interface StoredEventsData {
     channels: ChannelConfig[];
     events: EventEnvelope[];
@@ -122,10 +159,26 @@ export interface EmitResult<TData extends EventData = EventData> {
     deliveries: DeliveryResult[];
     deduped: boolean;
 }
+export type EventsStorageMode = "local-files" | "local-sqlite" | "remote-postgres" | "remote-s3" | "remote-aws" | "custom";
+export interface EventsStoreRuntime {
+    mode: EventsStorageMode;
+    name: string;
+    remote: boolean;
+    localFiles: boolean;
+    localSqlite: boolean;
+    postgres: boolean;
+    s3: boolean;
+    aws: boolean;
+    durable: boolean;
+    idempotency: "best-effort-local" | "atomic-store" | "consumer-owned";
+    replayCursors: boolean;
+    description: string;
+}
 export interface EventsStatus {
     service: "events";
     schemaVersion: "1.0";
     dataDir: string;
+    storage: EventsStoreRuntime;
     env: {
         primary: "HASNA_EVENTS_DIR";
         fallback: "HASNA_EVENTS_HOME";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,10 @@
       "types": "./dist/transports.d.ts",
       "import": "./dist/transports.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js"
+    },
     "./commander": {
       "types": "./dist/commander.d.ts",
       "import": "./dist/commander.js"
@@ -45,7 +49,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts --outdir dist --target bun && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts src/catalog.ts --outdir dist --target bun && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "prepublishOnly": "bun run test && bun run build"