From 837a05e54d02287fcde5d64ac239b441fef15ab7 Mon Sep 17 00:00:00 2001
From: Alex Gleason <alex@alexgleason.me>
Date: Sat, 26 Aug 2023 13:32:15 -0500
Subject: [PATCH] Add kinds module to classify events by kind

---
 kinds.test.ts | 20 ++++++++++++++++++++
 kinds.ts      | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 kinds.test.ts
 create mode 100644 kinds.ts

diff --git a/kinds.test.ts b/kinds.test.ts
new file mode 100644
index 0000000..a4f3b72
--- /dev/null
+++ b/kinds.test.ts
@@ -0,0 +1,20 @@
+import {classifyKind} from './kinds.ts'
+
+test('kind classification', () => {
+  expect(classifyKind(1)).toBe('regular')
+  expect(classifyKind(5)).toBe('regular')
+  expect(classifyKind(6)).toBe('regular')
+  expect(classifyKind(7)).toBe('regular')
+  expect(classifyKind(1000)).toBe('regular')
+  expect(classifyKind(9999)).toBe('regular')
+  expect(classifyKind(0)).toBe('replaceable')
+  expect(classifyKind(3)).toBe('replaceable')
+  expect(classifyKind(10000)).toBe('replaceable')
+  expect(classifyKind(19999)).toBe('replaceable')
+  expect(classifyKind(20000)).toBe('ephemeral')
+  expect(classifyKind(29999)).toBe('ephemeral')
+  expect(classifyKind(30000)).toBe('parameterized')
+  expect(classifyKind(39999)).toBe('parameterized')
+  expect(classifyKind(40000)).toBe('unknown')
+  expect(classifyKind(255)).toBe('unknown')
+})
diff --git a/kinds.ts b/kinds.ts
new file mode 100644
index 0000000..adb358f
--- /dev/null
+++ b/kinds.ts
@@ -0,0 +1,40 @@
+/** Events are **regular**, which means they're all expected to be stored by relays. */
+function isRegularKind(kind: number) {
+  return (1000 <= kind && kind < 10000) || [1, 2, 4, 5, 6, 7, 8, 16, 40, 41, 42, 43, 44].includes(kind)
+}
+
+/** Events are **replaceable**, which means that, for each combination of `pubkey` and `kind`, only the latest event is expected to (SHOULD) be stored by relays, older versions are expected to be discarded. */
+function isReplaceableKind(kind: number) {
+  return (10000 <= kind && kind < 20000) || [0, 3].includes(kind)
+}
+
+/** Events are **ephemeral**, which means they are not expected to be stored by relays. */
+function isEphemeralKind(kind: number) {
+  return 20000 <= kind && kind < 30000
+}
+
+/** Events are **parameterized replaceable**, which means that, for each combination of `pubkey`, `kind` and the `d` tag, only the latest event is expected to be stored by relays, older versions are expected to be discarded. */
+function isParameterizedReplaceableKind(kind: number) {
+  return 30000 <= kind && kind < 40000
+}
+
+/** Classification of the event kind. */
+type KindClassification = 'regular' | 'replaceable' | 'ephemeral' | 'parameterized' | 'unknown'
+
+/** Determine the classification of this kind of event if known, or `unknown`. */
+function classifyKind(kind: number): KindClassification {
+  if (isRegularKind(kind)) return 'regular'
+  if (isReplaceableKind(kind)) return 'replaceable'
+  if (isEphemeralKind(kind)) return 'ephemeral'
+  if (isParameterizedReplaceableKind(kind)) return 'parameterized'
+  return 'unknown'
+}
+
+export {
+  classifyKind,
+  isEphemeralKind,
+  isParameterizedReplaceableKind,
+  isRegularKind,
+  isReplaceableKind,
+  type KindClassification,
+}