@zoobzio/kit 0.0.0-stage → 0.0.0

package/.dist/index.d.mts

@@ -0,0 +1,94 @@
+/**
+ * One middleware slot per field of a state container `S`. A slot receives
+ * the value of its field and returns the value the service uses. A missing
+ * slot passes the value on.
+ */
+export type Middleware<S> = { [K in keyof S]?: (value: S[K]) => S[K]; };
+/**
+ * The middleware for reads and writes of a state container.
+ */
+export type Options<S> = {
+  get?: {
+    state?: Middleware<S>;
+  };
+  set?: {
+    state?: Middleware<S>;
+  };
+};
+/**
+ * The fields of a state container, as a record keyed by field name. The
+ * proxy uses the keys to tell a container field from any other key.
+ */
+export type Fields<S> = Record<keyof S, null>;
+/**
+ * The change object of each field: the field name with the stored values
+ * around the write, after the `set` middleware.
+ */
+export type Changes<S> = { [K in keyof S]: {
+  field: K;
+  before: S[K];
+  after: S[K];
+}; };
+/**
+ * A write to one field of the container. With no `K`, the union over every
+ * field; `field` discriminates.
+ */
+export type Change<S, K extends keyof S = keyof S> = Changes<S>[K];
+/**
+ * The change builder of each field. A lookup by a generic key yields the
+ * change object of that field, which an object literal cannot express
+ * without a cast.
+ */
+export type Changers<S> = { [K in keyof S]: (field: K, before: S[K], after: S[K]) => Changes<S>[K]; };
+/**
+ * The one event every state container emits: `change`, with the change
+ * object of the written field. A service's event map extends this.
+ */
+export type ChangeEvents<S> = {
+  change: [change: Change<S>];
+};
+/**
+ * An event map: each key is an event name, each value the argument list of
+ * its listeners.
+ */
+export type EventMap = Record<string, unknown[]>;
+/**
+ * A typed event bus over an event map.
+ */
+export type Emitter<M extends EventMap> = {
+  /**
+   * Subscribes a listener to an event. Returns the function that removes it.
+   */
+  on: <E extends keyof M>(event: E, listener: (...args: M[E]) => void) => () => void;
+  /**
+   * Calls the listeners of an event, in subscription order, over a copy, so
+   * a listener can unsubscribe during the call.
+   */
+  emit: <E extends keyof M>(event: E, ...args: M[E]) => void;
+  /**
+   * Whether an event has a listener. Skips the work of an event payload when
+   * nothing listens.
+   */
+  heard: (event: keyof M) => boolean;
+};
+/**
+ * A listener of one event of an event map.
+ */
+export type Listener<M extends EventMap, E extends keyof M> = (...args: M[E]) => void;
+export type Listeners<M extends EventMap> = { [E in keyof M]?: Set<(...args: M[E]) => void>; };
+/**
+ * Makes a typed event bus. Listener sets are created on first use.
+ */
+export declare const makeEmitter: <M extends EventMap>() => Emitter<M>;
+/**
+ * Makes the active state over a container: an `S`-shaped proxy. A read of
+ * a field passes the stored value through the matching `options.get`
+ * middleware. A write passes the value through the matching `options.set`
+ * middleware, stores the result in the container, and emits `change` with
+ * one change object. A key outside `fields` goes straight to the container.
+ */
+export declare const makeProxy: <S extends object>(state: S, fields: Fields<S>, options: Options<S>, emitter: Emitter<ChangeEvents<S>>) => S;
+/**
+ * Builds the change object of a field.
+ */
+export declare const change: <S, K extends keyof S>(field: K, before: S[K], after: S[K]) => Changes<S>[K];

package/.dist/index.mjs

@@ -0,0 +1,47 @@
+import { keys, rekey, within } from "objectively";
+const makeEmitter = () => {
+	const listeners = {};
+	const of = (event) => listeners[event] ??= /* @__PURE__ */ new Set();
+	return {
+		on: (event, listener) => {
+			of(event).add(listener);
+			return () => {
+				of(event).delete(listener);
+			};
+		},
+		emit: (event, ...args) => {
+			for (const listener of Array.from(of(event))) listener(...args);
+		},
+		heard: (event) => of(event).size > 0
+	};
+};
+const change = (field, before, after) => ({
+	field,
+	before,
+	after
+});
+const makeProxy = (state, fields, options, emitter) => {
+	const names = keys(fields);
+	const changers = rekey(fields, (field) => [field, change]);
+	const read = (key) => {
+		const through = options.get?.state?.[key];
+		const value = state[key];
+		return through ? through(value) : value;
+	};
+	const write = (key, value) => {
+		const through = options.set?.state?.[key];
+		const before = state[key];
+		const after = through ? through(value) : value;
+		state[key] = after;
+		if (emitter.heard("change")) emitter.emit("change", changers[key](key, before, after));
+	};
+	return new Proxy(state, {
+		get: (target, key) => within(names, key) ? read(key) : Reflect.get(target, key),
+		set: (target, key, value) => {
+			if (!within(names, key)) return Reflect.set(target, key, value);
+			write(key, value);
+			return true;
+		}
+	});
+};
+export { change, makeEmitter, makeProxy };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alexander Thorwaldson
+
+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.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @zoobzio/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The mechanisms the headless services share. Pure TypeScript, no framework
+dependency.
+
+- `makeEmitter<M>()`: a typed event bus over an event map. `on` subscribes and
+  returns the unsubscribe, `emit` calls listeners in subscription order over a
+  copy, `heard` reports whether an event has a listener.
+- `makeProxy(state, fields, options, emitter)`: the active state over a
+  container. A read of a field passes through `options.get.state.<field>`, a
+  write through `options.set.state.<field>`, then lands in the container and
+  emits `change` with `{ field, before, after }`. A key outside `fields` goes
+  straight to the container.
+- `change(field, before, after)`: builds one change object.
+- The types the above are described in: `Middleware<S>`, `Options<S>`,
+  `Fields<S>`, `Changes<S>`, `Change<S, K>`, `Changers<S>`, `ChangeEvents<S>`,
+  `EventMap`, `Emitter<M>`, `Listener<M, E>`, `Listeners<M>`.
+
+Everything is generic over the container shape `S`. A service binds them to
+its own `State<T>` and re-exports the bound aliases, so a consumer of
+`@zoobzio/table` never imports from the kit directly.
+
+## Usage
+
+```ts
+import { makeEmitter, makeProxy } from "@zoobzio/kit";
+import type { ChangeEvents, Fields, Options } from "@zoobzio/kit";
+
+type State = { page: number; query: string };
+
+const FIELDS: Fields<State> = { page: null, query: null };
+
+type Events = ChangeEvents<State> & { updated: [event: { id: string }] };
+
+const emitter = makeEmitter<Events>();
+const options: Options<State> = {
+  set: { state: { query: (query) => query.trim() } },
+};
+const state = makeProxy({ page: 1, query: "" }, FIELDS, options, emitter);
+
+emitter.on("change", (change) => {
+  if (change.field === "page") track(change.after);
+});
+
+state.query = " acme "; // stored as "acme", emits change
+```

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@zoobzio/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "The mechanisms the headless services share: a typed event emitter, a state container proxy with per-field middleware and change events, and the types that describe them. No framework dependency.",
+  "license": "MIT",
+  "author": {
+    "name": "Alex Thorwaldson",
+    "email": "alex@zoobz.io",
+    "url": "https://zoobz.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/foundation.git",
+    "directory": "packages/kit"
+  },
+  "files": [
+    ".dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.mts",
+      "import": "./.dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "objectively": "^0.3.0"
+  },
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }