applesauce-core 0.0.0-next-20251117171749 → 0.0.0-next-20251205152544

package/README.md

@@ -1,12 +1,16 @@
 # applesauce-core
 
-AppleSauce is a collection of utilities for building reactive nostr applications. The core package provides an in-memory event database and reactive models to help you build nostr UIs with less code.
+Applesauce is a collection of utilities for building reactive nostr applications. The core package provides protocol-level functionality including an in-memory event database, generic event utilities, and basic reactive models.
 
 ## Key Components
 
 - **Helpers**: Core utility methods for parsing and extracting data from nostr events
 - **EventStore**: In-memory database for storing and subscribing to nostr events
-- **Models**: Complex subscriptions for common nostr data patterns
+- **Helpers**: Core protocol-level utility methods for working with events, tags, filters, and pointers
+- **Models**: Generic models for common nostr data patterns (profiles, reactions, zaps, etc.)
+- **Observable**: RxJS utilities for reactive programming
+
+> **Note**: For NIP-specific helpers and models (NIP-10 threading, NIP-22 comments, NIP-53 streams, etc.), see the [`applesauce-common`](../common/README.md) package.
 
 ## Documentation
 

package/dist/event-factory/event-factory.d.ts

@@ -0,0 +1,57 @@
+import { EventTemplate, NostrEvent, UnsignedEvent } from "../helpers/event.js";
+import { ModifyTagsOptions } from "../operations/tags.js";
+import { EventFactoryTemplate } from "./methods.js";
+import { EventBlueprint, EventFactoryContext, EventOperation, IEventFactory } from "./types.js";
+/**
+ * Base class that provides event creation functionality.
+ * This class can be extended by other packages to add additional helpful event creation methods.
+ *
+ * @example
+ * ```ts
+ * // In another package (e.g., applesauce-common)
+ * import { EventFactory } from "applesauce-core/event-factory";
+ * import { NoteBlueprint, ReactionBlueprint } from "applesauce-common/blueprints";
+ *
+ * // Add methods to the prototype
+ * EventFactory.prototype.note = function(content, options) {
+ *   return this.create(NoteBlueprint, content, options);
+ * };
+ *
+ * EventFactory.prototype.reaction = function(event, emoji) {
+ *   return this.create(ReactionBlueprint, event, emoji);
+ * };
+ *
+ * // Extend the type via module augmentation
+ * declare module "applesauce-core/event-factory" {
+ *   interface EventFactory {
+ *     note(content: string, options?: NoteBlueprintOptions): Promise<EventTemplate>;
+ *     reaction(event: NostrEvent, emoji?: string): Promise<EventTemplate>;
+ *   }
+ * }
+ * ```
+ */
+export declare class EventFactory implements IEventFactory {
+    context: EventFactoryContext;
+    constructor(context?: EventFactoryContext);
+    /** Build an event template with operations */
+    build(template: EventFactoryTemplate, ...operations: (EventOperation | undefined)[]): Promise<EventTemplate>;
+    /** Create an event from a blueprint */
+    create<T extends EventTemplate | UnsignedEvent | NostrEvent>(blueprint: EventBlueprint<T>): Promise<T>;
+    create<T extends EventTemplate | UnsignedEvent | NostrEvent, Args extends Array<any>>(blueprint: (...args: Args) => EventBlueprint<T>, ...args: Args): Promise<T>;
+    /** Modify an existing event with operations and updated the created_at */
+    modify(draft: EventTemplate | UnsignedEvent | NostrEvent, ...operations: (EventOperation | undefined)[]): Promise<EventTemplate>;
+    /** Modify a lists public and hidden tags and updated the created_at */
+    modifyTags(event: EventTemplate | UnsignedEvent | NostrEvent, tagOperations?: ModifyTagsOptions, eventOperations?: EventOperation | (EventOperation | undefined)[]): Promise<EventTemplate>;
+    /** Attaches the signers pubkey to an event template */
+    stamp(draft: EventTemplate | UnsignedEvent): Promise<UnsignedEvent>;
+    /** Signs a event template with the signer */
+    sign(draft: EventTemplate | UnsignedEvent): Promise<NostrEvent>;
+    /** Sets the signer in the context */
+    setSigner(signer: EventFactoryContext["signer"]): void;
+    /** clears the signer in the context */
+    clearSigner(): void;
+    /** sets the client in the context */
+    setClient(client: EventFactoryContext["client"]): void;
+    /** clears the client in the context */
+    clearClient(): void;
+}

package/dist/event-factory/event-factory.js

@@ -0,0 +1,94 @@
+import { sign, stamp } from "../operations/event.js";
+import { modifyTags } from "../operations/tags.js";
+import { buildEvent, modifyEvent } from "./methods.js";
+/**
+ * Base class that provides event creation functionality.
+ * This class can be extended by other packages to add additional helpful event creation methods.
+ *
+ * @example
+ * ```ts
+ * // In another package (e.g., applesauce-common)
+ * import { EventFactory } from "applesauce-core/event-factory";
+ * import { NoteBlueprint, ReactionBlueprint } from "applesauce-common/blueprints";
+ *
+ * // Add methods to the prototype
+ * EventFactory.prototype.note = function(content, options) {
+ *   return this.create(NoteBlueprint, content, options);
+ * };
+ *
+ * EventFactory.prototype.reaction = function(event, emoji) {
+ *   return this.create(ReactionBlueprint, event, emoji);
+ * };
+ *
+ * // Extend the type via module augmentation
+ * declare module "applesauce-core/event-factory" {
+ *   interface EventFactory {
+ *     note(content: string, options?: NoteBlueprintOptions): Promise<EventTemplate>;
+ *     reaction(event: NostrEvent, emoji?: string): Promise<EventTemplate>;
+ *   }
+ * }
+ * ```
+ */
+export class EventFactory {
+    context;
+    constructor(context = {}) {
+        this.context = context;
+    }
+    /** Build an event template with operations */
+    async build(template, ...operations) {
+        return await buildEvent(template, this.context, ...operations);
+    }
+    async create(blueprint, ...args) {
+        // Context, blueprint(context)
+        if (arguments.length === 1) {
+            return (await blueprint(this.context));
+        }
+        // Context, blueprintConstructor(...args)(context), ...args
+        else {
+            const constructor = blueprint;
+            return await constructor(...args)(this.context);
+        }
+    }
+    /** Modify an existing event with operations and updated the created_at */
+    async modify(draft, ...operations) {
+        return await modifyEvent(draft, this.context, ...operations);
+    }
+    /** Modify a lists public and hidden tags and updated the created_at */
+    async modifyTags(event, tagOperations, eventOperations) {
+        let eventOperationsArr = [];
+        // normalize event operation arg
+        if (eventOperations === undefined)
+            eventOperationsArr = [];
+        else if (typeof eventOperations === "function")
+            eventOperationsArr = [eventOperations];
+        else if (Array.isArray(eventOperations))
+            eventOperationsArr = eventOperations.filter((e) => !!e);
+        // modify event
+        return await this.modify(event, modifyTags(tagOperations), ...eventOperationsArr);
+    }
+    /** Attaches the signers pubkey to an event template */
+    async stamp(draft) {
+        return await stamp()(draft, this.context);
+    }
+    /** Signs a event template with the signer */
+    async sign(draft) {
+        return await sign()(draft, this.context);
+    }
+    // Helpers
+    /** Sets the signer in the context */
+    setSigner(signer) {
+        this.context.signer = signer;
+    }
+    /** clears the signer in the context */
+    clearSigner() {
+        this.context.signer = undefined;
+    }
+    /** sets the client in the context */
+    setClient(client) {
+        this.context.client = client;
+    }
+    /** clears the client in the context */
+    clearClient() {
+        this.context.client = undefined;
+    }
+}

package/dist/event-factory/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./event-factory.js";
+export * from "./methods.js";

package/dist/event-factory/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./event-factory.js";
+export * from "./methods.js";

package/dist/event-factory/methods.d.ts

@@ -0,0 +1,17 @@
+import { EventTemplate, NostrEvent, UnsignedEvent } from "../helpers/event.js";
+import { EventBlueprint, EventFactoryContext, EventOperation } from "./types.js";
+export type EventFactoryTemplate = {
+    kind: number;
+    content?: string;
+    tags?: string[][];
+    created_at?: number;
+};
+/** Creates an event using a template, context, and a set of operations */
+export declare function buildEvent(template: EventFactoryTemplate, context: EventFactoryContext, ...operations: (EventOperation | undefined)[]): Promise<EventTemplate>;
+/** Creates a blueprint function with operations */
+export declare function blueprint(kind: number, ...operations: (EventOperation | undefined)[]): EventBlueprint;
+/** Creates an event from a context and a blueprint */
+export declare function createEvent<T extends EventTemplate | UnsignedEvent | NostrEvent>(context: EventFactoryContext, blueprint: EventBlueprint<T>): Promise<T>;
+export declare function createEvent<T extends EventTemplate | UnsignedEvent | NostrEvent, Args extends Array<any>>(context: EventFactoryContext, blueprintConstructor: (...args: Args) => EventBlueprint<T>, ...args: Args): Promise<T>;
+/** Modifies an event using a context and a set of operations */
+export declare function modifyEvent(event: EventTemplate | UnsignedEvent | NostrEvent, context: EventFactoryContext, ...operations: (EventOperation | undefined)[]): Promise<EventTemplate>;

package/dist/event-factory/methods.js

@@ -0,0 +1,40 @@
+import { EncryptedContentSymbol } from "../helpers/encrypted-content.js";
+import { eventPipe } from "../helpers/pipeline.js";
+import { unixNow } from "../helpers/time.js";
+import { setClient } from "../operations/client.js";
+import { includeReplaceableIdentifier, stripSignature, stripStamp, stripSymbols, updateCreatedAt, } from "../operations/event.js";
+/** Wraps a set of operations with common event operations */
+function wrapCommon(...operations) {
+    return eventPipe(
+    // Remove all symbols from the event except for the encrypted content symbol
+    stripSymbols([EncryptedContentSymbol]), 
+    // Ensure all addressable events have "d" tags
+    includeReplaceableIdentifier(), 
+    // Apply operations
+    ...operations, 
+    // Include client tag if its set in the context
+    (draft, ctx) => (ctx.client ? setClient(ctx.client.name, ctx.client.address)(draft, ctx) : draft));
+}
+/** Creates an event using a template, context, and a set of operations */
+export async function buildEvent(template, context, ...operations) {
+    return await wrapCommon(stripSignature(), stripStamp(), ...operations)({ created_at: unixNow(), tags: [], content: "", ...template }, context);
+}
+/** Creates a blueprint function with operations */
+export function blueprint(kind, ...operations) {
+    return async (context) => await buildEvent({ kind }, context, ...operations);
+}
+export async function createEvent(context, blueprint, ...args) {
+    // Context, blueprint(context)
+    if (arguments.length === 2) {
+        return (await blueprint(context));
+    }
+    // Context, blueprintConstructor(...args)(context), ...args
+    else {
+        const constructor = blueprint;
+        return await constructor(...args)(context);
+    }
+}
+/** Modifies an event using a context and a set of operations */
+export async function modifyEvent(event, context, ...operations) {
+    return await wrapCommon(stripSignature(), stripStamp(), updateCreatedAt(), ...operations)(event, context);
+}

package/dist/event-factory/types.d.ts

@@ -0,0 +1,76 @@
+import { EventTemplate, NostrEvent, UnsignedEvent } from "../helpers/event.js";
+import { AddressPointer } from "../helpers/pointers.js";
+import { ModifyTagsOptions } from "../operations/tags.js";
+import { EventFactoryTemplate } from "./methods.js";
+/** Nostr event signer */
+export interface EventSigner {
+    getPublicKey: () => Promise<string> | string;
+    signEvent: (draft: EventTemplate | UnsignedEvent) => Promise<NostrEvent> | NostrEvent;
+    nip04?: {
+        encrypt: (pubkey: string, plaintext: string) => Promise<string> | string;
+        decrypt: (pubkey: string, ciphertext: string) => Promise<string> | string;
+    };
+    nip44?: {
+        encrypt: (pubkey: string, plaintext: string) => Promise<string> | string;
+        decrypt: (pubkey: string, ciphertext: string) => Promise<string> | string;
+    };
+}
+/** A context with optional methods for getting relay hints */
+export interface RelayHintContext {
+    getEventRelayHint?: (event: string) => string | undefined | Promise<string> | Promise<undefined>;
+    getPubkeyRelayHint?: (pubkey: string) => string | undefined | Promise<string> | Promise<undefined>;
+}
+/** A context with an optional signer */
+export interface EventSignerContext {
+    signer?: EventSigner;
+}
+export interface EventFactoryClient {
+    name: string;
+    address?: Omit<AddressPointer, "kind" | "relays">;
+}
+/** A context with an optional NIP-89 app pointer */
+export interface ClientPointerContext {
+    client?: EventFactoryClient;
+}
+/** NIP-30 emoji type. this should be moved out of the core package to common */
+export type Emoji = {
+    /** The emoji shortcode (without the ::) */
+    shortcode: string;
+    /** The URL to the emoji image */
+    url: string;
+};
+export interface EmojiContext {
+    /** An array of custom emojis that will be used for text notes */
+    emojis?: Emoji[];
+}
+/** All options that can be passed when building an event */
+export interface EventFactoryContext extends ClientPointerContext, EventSignerContext, RelayHintContext, EmojiContext {
+}
+/** A single operation that modifies an events public or hidden tags array */
+export type Operation<I extends unknown = unknown, R extends unknown = unknown> = (value: I, context: EventFactoryContext) => R | Promise<R>;
+/** A single operation that modifies an events public or hidden tags array */
+export type TagOperation = Operation<string[][], string[][]>;
+/** A single operation that modifies an event */
+export type EventOperation<I extends EventTemplate | UnsignedEvent | NostrEvent = EventTemplate, R extends EventTemplate | UnsignedEvent | NostrEvent = EventTemplate> = Operation<I, R>;
+/** A method that creates a new event based on a set of operations */
+export type EventBlueprint<T extends EventTemplate | UnsignedEvent | NostrEvent = EventTemplate> = (context: EventFactoryContext) => Promise<T>;
+/**
+ * Core helpful event creation interface.
+ * Contains only methods that use blueprints from the core package.
+ * Other packages (like applesauce-common) can extend this interface via module augmentation.
+ */
+export interface IEventFactory {
+    /** Build an event template with operations */
+    build(template: EventFactoryTemplate, ...operations: (EventOperation | undefined)[]): Promise<EventTemplate>;
+    /** Create an event from a blueprint */
+    create<T extends EventTemplate | UnsignedEvent | NostrEvent>(blueprint: EventBlueprint<T>): Promise<T>;
+    create<T extends EventTemplate | UnsignedEvent | NostrEvent, Args extends Array<any>>(blueprint: (...args: Args) => EventBlueprint<T>, ...args: Args): Promise<T>;
+    /** Modify an existing event with operations and updated the created_at */
+    modify(draft: EventTemplate | UnsignedEvent | NostrEvent, ...operations: (EventOperation | undefined)[]): Promise<EventTemplate>;
+    /** Modify a lists public and hidden tags and updated the created_at */
+    modifyTags(event: EventTemplate | UnsignedEvent | NostrEvent, tagOperations?: ModifyTagsOptions, eventOperations?: EventOperation | (EventOperation | undefined)[]): Promise<EventTemplate>;
+    /** Attaches the signers pubkey to an event template */
+    stamp(draft: EventTemplate | UnsignedEvent): Promise<UnsignedEvent>;
+    /** Signs a event template with the signer */
+    sign(draft: EventTemplate | UnsignedEvent): Promise<NostrEvent>;
+}

package/dist/event-factory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/event-store/async-event-store.d.ts

@@ -1,44 +1,12 @@
-import { Filter, NostrEvent } from "nostr-tools";
-import { AddressPointer, EventPointer } from "nostr-tools/nip19";
 import { Observable, Subject } from "rxjs";
-import { AddressPointerWithoutD } from "../helpers/pointers.js";
+import { NostrEvent } from "../helpers/event.js";
+import { Filter } from "../helpers/filter.js";
+import { AddressPointer, AddressPointerWithoutD, EventPointer } from "../helpers/pointers.js";
 import { EventMemory } from "./event-memory.js";
+import { EventModels } from "./event-models.js";
 import { IAsyncEventDatabase, IAsyncEventStore } from "./interface.js";
-declare const AsyncEventStore_base: {
-    new (...args: any[]): {
-        [x: string]: any;
-        models: Map<import("./interface.js").ModelConstructor<any, any[], import("./interface.js").IEventStore | IAsyncEventStore>, Map<string, Observable<any>>>;
-        modelKeepWarm: number;
-        model<T extends unknown, Args extends Array<any>>(constructor: import("./interface.js").ModelConstructor<T, Args, import("./interface.js").IEventStore | IAsyncEventStore>, ...args: Args): Observable<T>;
-        filters(filters: Filter | Filter[], onlyNew?: boolean): Observable<NostrEvent>;
-        event(pointer: string | EventPointer): Observable<NostrEvent | undefined>;
-        replaceable(pointer: AddressPointer | AddressPointerWithoutD): Observable<NostrEvent | undefined>;
-        replaceable(kind: number, pubkey: string, identifier?: string): Observable<NostrEvent | undefined>;
-        addressable(pointer: AddressPointer): Observable<NostrEvent | undefined>;
-        timeline(filters: Filter | Filter[], includeOldVersion?: boolean): Observable<NostrEvent[]>;
-        profile(user: string | import("nostr-tools/nip19").ProfilePointer): Observable<import("../helpers/profile.js").ProfileContent | undefined>;
-        contacts(user: string | import("nostr-tools/nip19").ProfilePointer): Observable<import("nostr-tools/nip19").ProfilePointer[]>;
-        mutes(user: string | import("nostr-tools/nip19").ProfilePointer): Observable<import("../helpers/mutes.js").Mutes | undefined>;
-        mailboxes(user: string | import("nostr-tools/nip19").ProfilePointer): Observable<{
-            inboxes: string[];
-            outboxes: string[];
-        } | undefined>;
-        blossomServers(user: string | import("nostr-tools/nip19").ProfilePointer): Observable<URL[]>;
-        reactions(event: NostrEvent): Observable<import("nostr-tools").Event[]>;
-        thread(root: string | EventPointer | AddressPointer): Observable<import("../models/thread.js").Thread>;
-        comments(event: NostrEvent): Observable<import("nostr-tools").Event[]>;
-        events(ids: string[]): Observable<Record<string, NostrEvent | undefined>>;
-        replaceableSet(pointers: {
-            kind: number;
-            pubkey: string;
-            identifier?: string;
-        }[]): Observable<Record<string, NostrEvent | undefined>>;
-    };
-} & {
-    new (): {};
-};
 /** An async wrapper around an async event database that handles replaceable events, deletes, and models */
-export declare class AsyncEventStore extends AsyncEventStore_base implements IAsyncEventStore {
+export declare class AsyncEventStore extends EventModels implements IAsyncEventStore {
     database: IAsyncEventDatabase;
     /** Optional memory database for ensuring single event instances */
     memory: EventMemory;
@@ -46,32 +14,22 @@ export declare class AsyncEventStore extends AsyncEventStore_base implements IAs
     keepOldVersions: boolean;
     /** Enable this to keep expired events */
     keepExpired: boolean;
-    /**
-     * A method used to verify new events before added them
-     * @returns true if the event is valid, false if it should be ignored
-     */
-    verifyEvent?: (event: NostrEvent) => boolean;
+    /** The method used to verify events */
+    private _verifyEventMethod?;
+    /** Get the method used to verify events */
+    get verifyEvent(): undefined | ((event: NostrEvent) => boolean);
+    /** Sets the method used to verify events */
+    set verifyEvent(method: undefined | ((event: NostrEvent) => boolean));
     /** A stream of new events added to the store */
-    insert$: Subject<import("nostr-tools").Event>;
+    insert$: Subject<import("nostr-tools/core").Event>;
     /** A stream of events that have been updated */
-    update$: Subject<import("nostr-tools").Event>;
+    update$: Subject<import("nostr-tools/core").Event>;
     /** A stream of events that have been removed */
-    remove$: Subject<import("nostr-tools").Event>;
+    remove$: Subject<import("nostr-tools/core").Event>;
     /**
      * A method that will be called when an event isn't found in the store
-     * @experimental
-     */
-    eventLoader?: (pointer: EventPointer) => Observable<NostrEvent> | Promise<NostrEvent | undefined>;
-    /**
-     * A method that will be called when a replaceable event isn't found in the store
-     * @experimental
-     */
-    replaceableLoader?: (pointer: AddressPointerWithoutD) => Observable<NostrEvent> | Promise<NostrEvent | undefined>;
-    /**
-     * A method that will be called when an addressable event isn't found in the store
-     * @experimental
      */
-    addressableLoader?: (pointer: AddressPointer) => Observable<NostrEvent> | Promise<NostrEvent | undefined>;
+    eventLoader?: (pointer: EventPointer | AddressPointer | AddressPointerWithoutD) => Observable<NostrEvent> | Promise<NostrEvent | undefined>;
     constructor(database: IAsyncEventDatabase);
     /** A method to add all events to memory to ensure there is only ever a single instance of an event */
     private mapToMemory;
@@ -133,4 +91,3 @@ export declare class AsyncEventStore extends AsyncEventStore_base implements IAs
     /** Creates an observable that emits when event is updated */
     updated(event: string | NostrEvent): Observable<NostrEvent>;
 }
-export {};

package/dist/event-store/async-event-store.js

@@ -1,17 +1,15 @@
-import { kinds } from "nostr-tools";
-import { isAddressableKind } from "nostr-tools/kinds";
 import { EMPTY, filter, mergeMap, Subject, take } from "rxjs";
 import { getDeleteCoordinates, getDeleteIds } from "../helpers/delete.js";
-import { createReplaceableAddress, EventStoreSymbol, FromCacheSymbol, isReplaceable } from "../helpers/event.js";
+import { createReplaceableAddress, EventStoreSymbol, FromCacheSymbol, isAddressableKind, isReplaceable, kinds, } from "../helpers/event.js";
 import { getExpirationTimestamp } from "../helpers/expiration.js";
 import { parseCoordinate } from "../helpers/pointers.js";
 import { addSeenRelay, getSeenRelays } from "../helpers/relays.js";
 import { unixNow } from "../helpers/time.js";
 import { EventMemory } from "./event-memory.js";
-import { EventStoreModelMixin } from "./model-mixin.js";
+import { EventModels } from "./event-models.js";
+import { verifyEvent as coreVerifyEvent } from "nostr-tools/pure";
 /** An async wrapper around an async event database that handles replaceable events, deletes, and models */
-export class AsyncEventStore extends EventStoreModelMixin(class {
-}) {
+export class AsyncEventStore extends EventModels {
     database;
     /** Optional memory database for ensuring single event instances */
     memory;
@@ -19,11 +17,19 @@ export class AsyncEventStore extends EventStoreModelMixin(class {
     keepOldVersions = false;
     /** Enable this to keep expired events */
     keepExpired = false;
-    /**
-     * A method used to verify new events before added them
-     * @returns true if the event is valid, false if it should be ignored
-     */
-    verifyEvent;
+    /** The method used to verify events */
+    _verifyEventMethod = coreVerifyEvent;
+    /** Get the method used to verify events */
+    get verifyEvent() {
+        return this._verifyEventMethod;
+    }
+    /** Sets the method used to verify events */
+    set verifyEvent(method) {
+        this._verifyEventMethod = method;
+        if (method === undefined) {
+            console.warn("[applesauce-core] AsyncEventStore.verifyEvent is undefined; signature checks are disabled.");
+        }
+    }
     /** A stream of new events added to the store */
     insert$ = new Subject();
     /** A stream of events that have been updated */
@@ -32,19 +38,8 @@ export class AsyncEventStore extends EventStoreModelMixin(class {
     remove$ = new Subject();
     /**
      * A method that will be called when an event isn't found in the store
-     * @experimental
      */
     eventLoader;
-    /**
-     * A method that will be called when a replaceable event isn't found in the store
-     * @experimental
-     */
-    replaceableLoader;
-    /**
-     * A method that will be called when an addressable event isn't found in the store
-     * @experimental
-     */
-    addressableLoader;
     constructor(database) {
         super();
         this.database = database;

package/dist/event-store/event-memory.d.ts

@@ -1,5 +1,5 @@
-import { NostrEvent } from "nostr-tools";
-import { FilterWithAnd } from "../helpers/filter.js";
+import { NostrEvent } from "../helpers/event.js";
+import { Filter } from "../helpers/filter.js";
 import { LRU } from "../helpers/lru.js";
 import { IEventMemory } from "./interface.js";
 /** An in-memory database of events */
@@ -29,15 +29,15 @@ export declare class EventMemory implements IEventMemory {
     /** Gets the history of a replaceable event */
     getReplaceableHistory(kind: number, pubkey: string, identifier?: string): NostrEvent[] | undefined;
     /** Gets all events that match the filters */
-    getByFilters(filters: FilterWithAnd | FilterWithAnd[]): NostrEvent[];
+    getByFilters(filters: Filter | Filter[]): NostrEvent[];
     /** Gets a timeline of events that match the filters */
-    getTimeline(filters: FilterWithAnd | FilterWithAnd[]): NostrEvent[];
+    getTimeline(filters: Filter | Filter[]): NostrEvent[];
     /** Inserts an event into the database and notifies all subscriptions */
     add(event: NostrEvent): NostrEvent;
     /** Removes an event from the database and notifies all subscriptions */
     remove(eventOrId: string | NostrEvent): boolean;
     /** Remove multiple events that match the given filters */
-    removeByFilters(filters: FilterWithAnd | FilterWithAnd[]): number;
+    removeByFilters(filters: Filter | Filter[]): number;
     /** Notify the database that an event has updated */
     update(_event: NostrEvent): void;
     /** A weak map of events to claim reference counts */
@@ -77,9 +77,9 @@ export declare class EventMemory implements IEventMemory {
     /** Iterates over all events by id */
     iterateIds(ids: Iterable<string>): Generator<NostrEvent>;
     /** Returns all events that match the filter */
-    protected getEventsForFilter(filter: FilterWithAnd): Set<NostrEvent>;
+    protected getEventsForFilter(filter: Filter): Set<NostrEvent>;
     /** Returns all events that match the filters */
-    protected getEventsForFilters(filters: FilterWithAnd[]): Set<NostrEvent>;
+    protected getEventsForFilters(filters: Filter[]): Set<NostrEvent>;
     /** Resets the event set */
     reset(): void;
 }

package/dist/event-store/event-memory.js

@@ -1,6 +1,5 @@
-import { binarySearch, insertEventIntoDescendingList } from "nostr-tools/utils";
-import { getIndexableTags, INDEXABLE_TAGS } from "../helpers/event-tags.js";
-import { createReplaceableAddress, isReplaceable } from "../helpers/event.js";
+import { binarySearch, createReplaceableAddress, insertEventIntoDescendingList, isReplaceable, } from "../helpers/event.js";
+import { getIndexableTags, INDEXABLE_TAGS } from "../helpers/filter.js";
 import { LRU } from "../helpers/lru.js";
 import { logger } from "../logger.js";
 /** An in-memory database of events */
@@ -377,7 +376,7 @@ export class EventMemory {
             time = Array.from(this.iterateTime(filter.since, filter.until));
             and(time);
         }
-        // Process AND tag filters (& prefix) first - NIP-ND
+        // Process AND tag filters (& prefix) first - NIP-91
         // AND takes precedence and requires ALL values to be present
         for (const t of INDEXABLE_TAGS) {
             const key = `&${t}`;
@@ -391,7 +390,7 @@ export class EventMemory {
             }
         }
         // Process OR tag filters (# prefix)
-        // Skip values that are in AND tags (NIP-ND rule)
+        // Skip values that are in AND tags (NIP-91 rule)
         for (const t of INDEXABLE_TAGS) {
             const key = `#${t}`;
             const values = filter[key];
@@ -399,7 +398,7 @@ export class EventMemory {
                 // Check if there's a corresponding AND filter for this tag
                 const andKey = `&${t}`;
                 const andValues = filter[andKey];
-                // Filter out values that are in AND tags (NIP-ND rule)
+                // Filterout values that are in AND tags (NIP-91 rule)
                 const filteredValues = andValues ? values.filter((v) => !andValues.includes(v)) : values;
                 // Only apply OR filter if there are values left after filtering
                 if (filteredValues.length > 0)

package/dist/event-store/event-models.d.ts

@@ -0,0 +1,76 @@
+import { Observable } from "rxjs";
+import { NostrEvent } from "../helpers/event.js";
+import { Filter } from "../helpers/filter.js";
+import { AddressPointer, AddressPointerWithoutD, EventPointer, ProfilePointer } from "../helpers/pointers.js";
+import { ProfileContent } from "../helpers/profile.js";
+import { IAsyncEventStore, IEventStore, ModelConstructor } from "./interface.js";
+/**
+ * Core helpful subscriptions interface.
+ * Contains only methods that use models from the core package.
+ * Other packages (like applesauce-common) can extend this interface via module augmentation.
+ */
+export interface IEventStoreModels {
+    /** Subscribe to a users profile */
+    profile(user: string | ProfilePointer): Observable<ProfileContent | undefined>;
+    /** Subscribe to a users contacts */
+    contacts(user: string | ProfilePointer): Observable<ProfilePointer[]>;
+    /** Subscribe to a users mailboxes */
+    mailboxes(user: string | ProfilePointer): Observable<{
+        inboxes: string[];
+        outboxes: string[];
+    } | undefined>;
+}
+/**
+ * Base class that provides model functionality for both sync and async event stores.
+ * This class can be extended by other packages to add additional helpful subscription methods.
+ *
+ * @example
+ * ```ts
+ * // In another package (e.g., applesauce-common)
+ * import { EventModels } from "applesauce-core/event-store";
+ *
+ * // Add methods to the prototype
+ * EventModels.prototype.mutes = function(user) {
+ *   return this.model(MuteModel, user);
+ * };
+ *
+ * // Extend the type via module augmentation
+ * declare module "applesauce-core/event-store" {
+ *   interface EventModels {
+ *     mutes(user: string | ProfilePointer): Observable<Mutes | undefined>;
+ *   }
+ * }
+ * ```
+ */
+export declare class EventModels<TStore extends IEventStore | IAsyncEventStore = IEventStore | IAsyncEventStore> implements IEventStoreModels {
+    /** A directory of all active models */
+    models: Map<ModelConstructor<any, any[], TStore>, Map<string, Observable<any>>>;
+    /** How long a model should be kept "warm" while nothing is subscribed to it */
+    modelKeepWarm: number;
+    /** Get or create a model on the event store */
+    model<T extends unknown, Args extends Array<any>>(constructor: ModelConstructor<T, Args, TStore>, ...args: Args): Observable<T>;
+    /**
+     * Creates an observable that streams all events that match the filter
+     * @param filters
+     * @param [onlyNew=false] Only subscribe to new events
+     */
+    filters(filters: Filter | Filter[], onlyNew?: boolean): Observable<NostrEvent>;
+    /** Creates a {@link EventModel} */
+    event(pointer: string | EventPointer): Observable<NostrEvent | undefined>;
+    /** Subscribe to a replaceable event by pointer */
+    replaceable(pointer: AddressPointer | AddressPointerWithoutD): Observable<NostrEvent | undefined>;
+    replaceable(kind: number, pubkey: string, identifier?: string): Observable<NostrEvent | undefined>;
+    /** Subscribe to an addressable event by pointer */
+    addressable(pointer: AddressPointer): Observable<NostrEvent | undefined>;
+    /** Creates a {@link TimelineModel} */
+    timeline(filters: Filter | Filter[], includeOldVersion?: boolean): Observable<NostrEvent[]>;
+    /** Subscribe to a users profile */
+    profile(user: string | ProfilePointer): Observable<ProfileContent | undefined>;
+    /** Subscribe to a users contacts */
+    contacts(user: string | ProfilePointer): Observable<ProfilePointer[]>;
+    /** Subscribe to a users mailboxes */
+    mailboxes(user: string | ProfilePointer): Observable<{
+        inboxes: string[];
+        outboxes: string[];
+    } | undefined>;
+}