@hashtree/nostr 0.1.13 → 0.2.3

package/src/eventCollection.ts

@@ -0,0 +1,189 @@
+import {
+  COLLECTION_MANIFEST_METADATA_FILE,
+  CollectionSource,
+  CollectionWriter,
+  collectionManifestMetadataFromManifest,
+  deserializeCid,
+  serializeCid,
+  type CollectionDefinition,
+  type CollectionManifest,
+  type CollectionManifestIndex,
+  type CollectionPublishedSchema,
+} from '@hashtree/collection';
+import type { Store } from '@hashtree/core';
+import {
+  authorKindTimeKey,
+  authorTimeKey,
+  getDTag,
+  isParameterizedReplaceableKind,
+  isReplaceableKind,
+  kindTimeKey,
+  MANIFEST_BY_AUTHOR_KIND_TIME,
+  MANIFEST_BY_AUTHOR_TIME,
+  MANIFEST_BY_ID,
+  MANIFEST_BY_KIND_TIME,
+  MANIFEST_BY_KIND_TIME_AUTHOR,
+  MANIFEST_BY_TAG,
+  MANIFEST_BY_TIME,
+  MANIFEST_PARAMETERIZED_REPLACEABLE,
+  MANIFEST_REPLACEABLE,
+  kindTimeAuthorKey,
+  parameterizedReplaceableKey,
+  replaceableKey,
+  tagKeys,
+  timeKey,
+} from './eventKeys.js';
+import { validateEventShape } from './eventValidation.js';
+import type { NostrEventManifest, StoredNostrEvent } from './events.js';
+
+export const DEFAULT_NOSTR_EVENT_COLLECTION_SOURCE_ID = 'nostr-events';
+export const NOSTR_EVENT_ITEM_FORMAT = 'nostr/event@1';
+export const NOSTR_EVENT_PROJECTION_FORMAT = 'hashtree/nostr-event-index@1';
+export { COLLECTION_MANIFEST_METADATA_FILE };
+
+const NOSTR_EVENT_PUBLISHED_SCHEMA: CollectionPublishedSchema = {
+  itemFormat: NOSTR_EVENT_ITEM_FORMAT,
+  projectionFormat: NOSTR_EVENT_PROJECTION_FORMAT,
+};
+
+export function createNostrEventCollectionDefinition(
+  sourceId: string = DEFAULT_NOSTR_EVENT_COLLECTION_SOURCE_ID,
+): CollectionDefinition<StoredNostrEvent> {
+  return {
+    sourceId,
+    schema: {
+      version: 1,
+      validate: (event) => {
+        validateEventShape(event);
+      },
+    },
+    publishedSchema: NOSTR_EVENT_PUBLISHED_SCHEMA,
+    getId: (event) => event.id,
+    keyIndexes: [
+      {
+        name: MANIFEST_BY_AUTHOR_TIME,
+        keys: (event) => [authorTimeKey(event)],
+      },
+      {
+        name: MANIFEST_BY_AUTHOR_KIND_TIME,
+        keys: (event) => [authorKindTimeKey(event)],
+      },
+      {
+        name: MANIFEST_BY_KIND_TIME,
+        keys: (event) => [kindTimeKey(event)],
+      },
+      {
+        name: MANIFEST_BY_KIND_TIME_AUTHOR,
+        keys: (event) => [kindTimeAuthorKey(event)],
+      },
+      {
+        name: MANIFEST_BY_TIME,
+        keys: (event) => [timeKey(event)],
+      },
+      {
+        name: MANIFEST_BY_TAG,
+        keys: (event) => tagKeys(event),
+      },
+      {
+        name: MANIFEST_REPLACEABLE,
+        keys: (event) => (
+          isReplaceableKind(event.kind)
+            ? [replaceableKey(event.pubkey, event.kind)]
+            : []
+        ),
+      },
+      {
+        name: MANIFEST_PARAMETERIZED_REPLACEABLE,
+        keys: (event) => (
+          isParameterizedReplaceableKind(event.kind)
+            ? [parameterizedReplaceableKey(event.pubkey, event.kind, getDTag(event) ?? '')]
+            : []
+        ),
+      },
+    ],
+  };
+}
+
+export function nostrEventManifestToCollectionManifest(
+  manifest: NostrEventManifest,
+  sourceId: string = DEFAULT_NOSTR_EVENT_COLLECTION_SOURCE_ID,
+): CollectionManifest {
+  const indexes: Record<string, CollectionManifestIndex> = {
+    [MANIFEST_BY_AUTHOR_TIME]: { kind: 'key', root: serializeCid(manifest.byAuthorTime) },
+    [MANIFEST_BY_AUTHOR_KIND_TIME]: { kind: 'key', root: serializeCid(manifest.byAuthorKindTime) },
+    [MANIFEST_BY_KIND_TIME]: { kind: 'key', root: serializeCid(manifest.byKindTime) },
+    [MANIFEST_BY_KIND_TIME_AUTHOR]: { kind: 'key', root: serializeCid(manifest.byKindTimeAuthor) },
+    [MANIFEST_BY_TIME]: { kind: 'key', root: serializeCid(manifest.byTime) },
+    [MANIFEST_BY_TAG]: { kind: 'key', root: serializeCid(manifest.byTag) },
+    [MANIFEST_REPLACEABLE]: { kind: 'key', root: serializeCid(manifest.replaceable) },
+    [MANIFEST_PARAMETERIZED_REPLACEABLE]: {
+      kind: 'key',
+      root: serializeCid(manifest.parameterizedReplaceable),
+    },
+  };
+
+  return {
+    version: 1,
+    sourceId,
+    schemaVersion: 1,
+    updatedAt: 0,
+    byIdRoot: serializeCid(manifest.byId),
+    indexes,
+    publishedSchema: NOSTR_EVENT_PUBLISHED_SCHEMA,
+  };
+}
+
+export function collectionManifestToNostrEventManifest(manifest: CollectionManifest): NostrEventManifest {
+  const byId = deserializeCid(manifest.byIdRoot);
+  const keyIndexCid = (name: string) => {
+    const index = manifest.indexes[name];
+    if (!index?.root) {
+      return null;
+    }
+    return deserializeCid(index.root);
+  };
+
+  return {
+    byId,
+    byAuthorTime: keyIndexCid(MANIFEST_BY_AUTHOR_TIME),
+    byAuthorKindTime: keyIndexCid(MANIFEST_BY_AUTHOR_KIND_TIME),
+    byKindTime: keyIndexCid(MANIFEST_BY_KIND_TIME),
+    byKindTimeAuthor: keyIndexCid(MANIFEST_BY_KIND_TIME_AUTHOR),
+    byTime: keyIndexCid(MANIFEST_BY_TIME),
+    byTag: keyIndexCid(MANIFEST_BY_TAG),
+    replaceable: keyIndexCid(MANIFEST_REPLACEABLE),
+    parameterizedReplaceable: keyIndexCid(MANIFEST_PARAMETERIZED_REPLACEABLE),
+  };
+}
+
+export async function createNostrEventCollectionSource(
+  store: Store,
+  manifest: NostrEventManifest,
+  sourceId: string = DEFAULT_NOSTR_EVENT_COLLECTION_SOURCE_ID,
+): Promise<CollectionSource> {
+  const collectionManifest = nostrEventManifestToCollectionManifest(manifest, sourceId);
+  return new CollectionSource(store, collectionManifest);
+}
+
+export function createNostrEventCollectionWriter(
+  store: Store,
+  manifest: NostrEventManifest,
+  sourceId: string = DEFAULT_NOSTR_EVENT_COLLECTION_SOURCE_ID,
+): CollectionWriter<StoredNostrEvent> {
+  return new CollectionWriter(
+    store,
+    createNostrEventCollectionDefinition(sourceId),
+    nostrEventManifestToCollectionManifest(manifest, sourceId),
+  );
+}
+
+export function nostrEventCollectionManifestMetadata(
+  manifest: NostrEventManifest,
+  sourceId: string = DEFAULT_NOSTR_EVENT_COLLECTION_SOURCE_ID,
+) {
+  return collectionManifestMetadataFromManifest(
+    nostrEventManifestToCollectionManifest(manifest, sourceId),
+  );
+}
+
+export const nostrEventCollectionRootMetadata = nostrEventCollectionManifestMetadata;

package/src/eventKeys.ts

@@ -0,0 +1,155 @@
+import type { StoredNostrEvent } from './events.js';
+
+const MAX_U64 = (1n << 64n) - 1n;
+
+export const MANIFEST_BY_ID = 'by-id';
+export const MANIFEST_BY_AUTHOR_TIME = 'by-author-time';
+export const MANIFEST_BY_AUTHOR_KIND_TIME = 'by-author-kind-time';
+export const MANIFEST_BY_KIND_TIME = 'by-kind-time';
+export const MANIFEST_BY_KIND_TIME_AUTHOR = 'by-kind-time-author';
+export const MANIFEST_BY_TIME = 'by-time';
+export const MANIFEST_BY_TAG = 'by-tag';
+export const MANIFEST_REPLACEABLE = 'replaceable';
+export const MANIFEST_PARAMETERIZED_REPLACEABLE = 'parameterized-replaceable';
+
+export function padKind(kind: number): string {
+  return kind.toString(16).padStart(8, '0');
+}
+
+export function reverseTimestamp(createdAt: number): string {
+  return (MAX_U64 - BigInt(createdAt)).toString(16).padStart(16, '0');
+}
+
+export function isReplaceableKind(kind: number): boolean {
+  return kind === 0 || kind === 3 || (kind >= 10_000 && kind < 20_000);
+}
+
+export function isParameterizedReplaceableKind(kind: number): boolean {
+  return kind >= 30_000 && kind < 40_000;
+}
+
+export function getDTag(event: Pick<StoredNostrEvent, 'tags'>): string | null {
+  for (const tag of event.tags) {
+    if (tag[0] === 'd' && typeof tag[1] === 'string' && tag[1].length > 0) {
+      return tag[1];
+    }
+  }
+
+  return null;
+}
+
+export function compareEvents(a: StoredNostrEvent, b: StoredNostrEvent): number {
+  if (a.created_at !== b.created_at) {
+    return a.created_at - b.created_at;
+  }
+
+  return a.id.localeCompare(b.id);
+}
+
+export function compareReplaceableEvents(a: StoredNostrEvent, b: StoredNostrEvent): number {
+  if (a.created_at !== b.created_at) {
+    return a.created_at - b.created_at;
+  }
+
+  return b.id.localeCompare(a.id);
+}
+
+export function authorTimeKey(event: StoredNostrEvent): string {
+  return `${event.pubkey}:${reverseTimestamp(event.created_at)}:${event.id}`;
+}
+
+export function authorKindTimeKey(event: StoredNostrEvent): string {
+  return `${event.pubkey}:${padKind(event.kind)}:${reverseTimestamp(event.created_at)}:${event.id}`;
+}
+
+export function kindTimeKey(event: StoredNostrEvent): string {
+  return `${padKind(event.kind)}:${reverseTimestamp(event.created_at)}:${event.id}`;
+}
+
+export function kindTimeAuthorKey(event: StoredNostrEvent): string {
+  return `${padKind(event.kind)}:${reverseTimestamp(event.created_at)}:${event.pubkey}:${event.id}`;
+}
+
+export function timeKey(event: StoredNostrEvent): string {
+  return `${reverseTimestamp(event.created_at)}:${event.id}`;
+}
+
+export function createdAtFromIndexKey(key: string): number {
+  const parts = key.split(':');
+  if (parts.length < 2) {
+    throw new Error(`Invalid Nostr index key: ${key}`);
+  }
+
+  const reversed = parts[parts.length - 2];
+  const reversedTimestamp = BigInt(`0x${reversed}`);
+  const createdAt = MAX_U64 - reversedTimestamp;
+  if (createdAt > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`Created_at exceeds safe integer range in Nostr index key: ${key}`);
+  }
+
+  return Number(createdAt);
+}
+
+export function normalizeTagName(tagName: string): string {
+  if (tagName.length === 0) {
+    throw new Error('tag name must be non-empty');
+  }
+
+  return tagName.toLowerCase();
+}
+
+export function normalizeTagValue(tagName: string, tagValue: string): string {
+  return tagName === 't' ? tagValue.toLowerCase() : tagValue;
+}
+
+export function tagKeys(event: StoredNostrEvent): string[] {
+  return event.tags.flatMap((tag) => {
+    const [name, value] = tag;
+    if (!name || !value) {
+      return [];
+    }
+
+    const normalizedName = name.toLowerCase();
+    const normalizedValue = normalizeTagValue(normalizedName, value);
+    return [`${normalizedName}:${normalizedValue}:${reverseTimestamp(event.created_at)}:${event.id}`];
+  });
+}
+
+export function tagPrefix(tagName: string, tagValue: string): string {
+  const normalizedName = normalizeTagName(tagName);
+  return `${normalizedName}:${normalizeTagValue(normalizedName, tagValue)}:`;
+}
+
+export function replaceableKey(pubkey: string, kind: number): string {
+  return `${pubkey}:${padKind(kind)}`;
+}
+
+export function parameterizedReplaceableKey(pubkey: string, kind: number, dTag: string): string {
+  return `${pubkey}:${padKind(kind)}:${dTag}`;
+}
+
+export function retainLatestReplaceableEvents(events: StoredNostrEvent[]): StoredNostrEvent[] {
+  const retained = new Map<string, StoredNostrEvent>();
+  const passthrough: StoredNostrEvent[] = [];
+
+  for (const event of events) {
+    let slot: string | null = null;
+    if (isReplaceableKind(event.kind)) {
+      slot = `replaceable:${replaceableKey(event.pubkey, event.kind)}`;
+    } else if (isParameterizedReplaceableKind(event.kind)) {
+      slot = `parameterized:${parameterizedReplaceableKey(event.pubkey, event.kind, getDTag(event) ?? '')}`;
+    }
+
+    if (!slot) {
+      passthrough.push(event);
+      continue;
+    }
+
+    const existing = retained.get(slot);
+    if (!existing || compareReplaceableEvents(event, existing) > 0) {
+      retained.set(slot, event);
+    }
+  }
+
+  return [...passthrough, ...retained.values()];
+}

package/src/eventValidation.ts

@@ -0,0 +1,71 @@
+import type { StoredNostrEvent } from './events.js';
+
+export const HEX_64 = /^[0-9a-f]{64}$/;
+export const HEX_128 = /^[0-9a-f]{128}$/;
+
+export function assertStringArray(tags: unknown): asserts tags is string[][] {
+  if (!Array.isArray(tags)) {
+    throw new Error('Nostr event tags must be an array');
+  }
+
+  for (const tag of tags) {
+    if (!Array.isArray(tag) || tag.some((value) => typeof value !== 'string')) {
+      throw new Error('Nostr event tags must be an array of string arrays');
+    }
+  }
+}
+
+export function validateHex64(value: string, label: string): string {
+  if (!HEX_64.test(value)) {
+    throw new Error(`${label} must be a lowercase 64-character hex string`);
+  }
+
+  return value;
+}
+
+export function validateHex128(value: string, label: string): string {
+  if (!HEX_128.test(value)) {
+    throw new Error(`${label} must be a lowercase 128-character hex string`);
+  }
+
+  return value;
+}
+
+export function validateCreatedAt(value: number): number {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error('created_at must be a non-negative integer');
+  }
+
+  return value;
+}
+
+export function validateKind(value: number): number {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error('kind must be a non-negative integer');
+  }
+
+  return value;
+}
+
+export function validateContent(value: string): string {
+  if (typeof value !== 'string') {
+    throw new Error('content must be a string');
+  }
+
+  return value;
+}
+
+export function validateEventShape(event: StoredNostrEvent): StoredNostrEvent {
+  const normalized = {
+    id: validateHex64(event.id, 'event id'),
+    pubkey: validateHex64(event.pubkey, 'pubkey'),
+    created_at: validateCreatedAt(event.created_at),
+    kind: validateKind(event.kind),
+    tags: event.tags,
+    content: validateContent(event.content),
+    sig: validateHex128(event.sig, 'signature'),
+  };
+
+  assertStringArray(normalized.tags);
+  return normalized;
+}