init

Author: rasulomaroff

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+coverage
+docs

.prettierrc

@@ -0,0 +1,8 @@
+{
+    "arrowParens": "avoid",
+    "semi": false,
+    "singleQuote": true,
+    "printWidth": 120,
+    "jsxBracketSameLine": false,
+    "tabWidth": 4
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rasulomaroff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eslint.config.ts

@@ -0,0 +1,30 @@
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import globals from 'globals'
+import prettier from 'eslint-plugin-prettier/recommended'
+
+export default [
+    eslint.configs.recommended,
+    ...tseslint.configs.recommendedTypeChecked,
+
+    { ignores: ['**/dist/**/*', '**/coverage/**', '**/node_modules/**', '**/docs/**'] },
+
+    {
+        rules: {
+            '@typescript-eslint/explicit-function-return-type': 'error',
+            '@typescript-eslint/consistent-type-definitions': 'off',
+            '@typescript-eslint/consistent-type-assertions': 'off',
+            // '@typescript-eslint/unbound-method': 'off',
+        },
+    },
+    {
+        languageOptions: {
+            globals: globals.browser,
+            parserOptions: {
+                projectService: true,
+                tsconfigRootDir: '.',
+            },
+        },
+    },
+    prettier,
+]

package.json

@@ -0,0 +1,48 @@
+{
+  "name": "evit",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "spec": "vitest run",
+    "doc": "typedoc",
+    "lint:check": "eslint .",
+    "type:check": "tsc --build ./tsconfig.typecheck.json --noEmit"
+  },
+  "description": "A lightweight, type-safe, and stateless event system for building reactive UIs. Designed to enable feature-level communication in large-scale applications using frameworks like React.",
+  "keywords": [
+    "event",
+    "emitter",
+    "react",
+    "hook",
+    "listener",
+    "subscription"
+  ],
+  "author": "rasulomaroff",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rasulomaroff/evit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rasulomaroff/evit/issues"
+  },
+  "homepage": "https://rasulomaroff.github.io/evit/",
+  "packageManager": "pnpm@10.12.1",
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "eslint": "^9.29.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.5.0",
+    "globals": "^16.2.0",
+    "happy-dom": "^18.0.1",
+    "jiti": "^2.4.2",
+    "prettier": "^3.6.0",
+    "tsup": "^8.5.0",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.0",
+    "vitest": "^3.2.4"
+  }
+}

packages/core/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@evit/core",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "A lightweight, type-safe, stateless event system for building reactive UIs.",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "node": "./dist/index.cjs",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "spec": "vitest run --typecheck",
+        "build": "tsup src/index.ts --format esm,cjs --dts --minify --clean --sourcemap"
+    },
+    "keywords": [
+        "event",
+        "emitter",
+        "react",
+        "hook",
+        "listener",
+        "subscription"
+    ],
+    "author": "rasulomaroff",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rasulomaroff/evit.git"
+    },
+    "bugs": {
+        "url": "https://github.com/rasulomaroff/evit/issues"
+    },
+    "homepage": "https://rasulomaroff.github.io/evit/",
+    "publishConfig": {
+        "access": "public"
+    }
+}

packages/core/src/event.spec-d.ts

@@ -0,0 +1,42 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import { defineEvent, withPayload } from './event'
+
+describe('defineEvent function', () => {
+    it('infers the tag type', () => {
+        const event = defineEvent('tag')
+
+        expectTypeOf(event.tag).toEqualTypeOf<'tag'>()
+    })
+
+    it('infers the payload type', () => {
+        const event = defineEvent('tag', { test: 22 })
+
+        expectTypeOf(event.tag).toEqualTypeOf<'tag'>()
+
+        event.on(payload => {
+            expectTypeOf(payload).toEqualTypeOf<{ test: number }>()
+        })
+    })
+
+    it('infers the payload type with the helper function', () => {
+        const event = defineEvent('tag', withPayload<{ age: number }>())
+
+        expectTypeOf(event.tag).toEqualTypeOf<'tag'>()
+
+        event.on(payload => {
+            expectTypeOf(payload).toEqualTypeOf<{ age: number }>()
+        })
+    })
+})
+
+describe('withPayload function', () => {
+    it('infers the type from the parameter and "returns" it', () => {
+        const user = withPayload<{ name: string; age: number }>()
+
+        expectTypeOf(user).toEqualTypeOf<{ name: string; age: number }>()
+
+        const num = withPayload<number>()
+
+        expectTypeOf(num).toBeNumber()
+    })
+})

packages/core/src/event.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest'
+import { defineEvent, mergeSubscriptions, withPayload } from './event'
+
+describe('defineEvent function', () => {
+    it('should call subscribed handler with tag', () => {
+        const handler = vi.fn()
+
+        const event = defineEvent('my.event')
+        event.on(handler)
+
+        event()
+
+        expect(handler).toHaveBeenCalledWith(undefined, event.tag)
+        expect(handler).toHaveBeenCalledTimes(1)
+        expect(event.tag).toBe('my.event')
+    })
+
+    it('should call subscribed handler with payload (using withPayload function) and tag', () => {
+        const handler = vi.fn()
+
+        const event = defineEvent('my.event', withPayload<number>())
+        event.on(handler)
+
+        event(42)
+
+        expect(handler).toHaveBeenCalledWith(42, event.tag)
+        expect(handler).toHaveBeenCalledTimes(1)
+        expect(event.tag).toBe('my.event')
+    })
+
+    it('should unsubscribe correctly', () => {
+        const handler = vi.fn()
+
+        const event = defineEvent('unsub.test', withPayload<string>())
+        const unsubscribe = event.on(handler)
+
+        event('hello')
+        unsubscribe()
+        event('world')
+
+        expect(handler).toHaveBeenCalledTimes(1)
+        expect(handler).toHaveBeenCalledWith('hello', event.tag)
+    })
+})
+
+describe('mergeSubscriptions function', () => {
+    it('should unsubscribe all passed callbacks', () => {
+        const unsub1 = vi.fn()
+        const unsub2 = vi.fn()
+
+        const merged = mergeSubscriptions(unsub1, unsub2)
+        merged()
+
+        expect(unsub1).toHaveBeenCalled()
+        expect(unsub2).toHaveBeenCalled()
+    })
+})

packages/core/src/event.ts

@@ -0,0 +1,78 @@
+import type { Action, EventHandler } from './types'
+
+/**
+ * Defines a new typed event with a payload and tag.
+ *
+ * @template Tag - A unique identifier for the event.
+ * @template P - The payload type.
+ *
+ * @param tag - The tag for the event.
+ * @param _infer - Optionally used to infer payload type (can use `withPayload<T>()`).
+ *
+ * @returns The event that you can subscribe to and listen.
+ *
+ * @example
+ * ```ts
+ * const event = defineEvent('user.created')
+ *
+ * // or with a payload
+ * const eventWithPayload = defineEvent('user.created', withPayload<{ id: number }>())
+ * ```
+ */
+export function defineEvent<const Tag, P = void>(
+    tag: Tag,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _infer?: P,
+): Action<P, Tag> {
+    const handlers = new Set<EventHandler<P, Action<P, Tag>>>()
+
+    const ev = ((payload: P): void => handlers.forEach(fn => fn(payload, tag))) as Action<P, Tag>
+
+    // @ts-expect-error we only assign this property once here
+    ev.tag = tag
+
+    ev.on = function on(fn: EventHandler<P, Action<P, Tag>>): () => void {
+        handlers.add(fn)
+
+        return (): void => {
+            handlers.delete(fn)
+        }
+    }
+
+    return ev
+}
+
+/**
+ * Utility function to help infer payload types when defining events.
+ * Does nothing at runtime.
+ *
+ * @example
+ * ```ts
+ * const event = defineEvent('user.updated', withPayload<{ id: string }>())
+ * ```
+ */
+export const withPayload = (() => {}) as <T>() => T
+
+/**
+ * A utility function to unsubscribe from multiple subscriptions at once.
+ *
+ * @param unsubscribers - An array of unsubscribe functions.
+ *
+ * @returns A single function that unsubscribes from all.
+ *
+ * @example
+ * ```ts
+ * const newUserEvent = defineEvent('user.created')
+ * const deleteUserEvent = defineEvent('user.deleted')
+ *
+ * const unsubscribe = mergeSubscriptions(
+ *     newUserEvent.on(() => {}),
+ *     deleteUserEvent.on(() => {}),
+ * )
+ * ```
+ */
+export function mergeSubscriptions(...unsubscribers: Array<() => void>): () => void {
+    return function unsubscribe(): void {
+        unsubscribers.forEach(fn => fn())
+    }
+}

packages/core/src/index.ts

@@ -0,0 +1,3 @@
+export { defineEvent, withPayload, mergeSubscriptions } from './event'
+
+export type { Action, EventHandler } from './types'