feature-core 0.0.1

package/LICENSE

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

@@ -0,0 +1,222 @@
+<h1 align="center">
+    <img src="https://raw.githubusercontent.com/builder-group/community/develop/packages/feature-core/.github/banner.svg" alt="feature-core banner">
+</h1>
+
+<p align="left">
+    <a href="https://github.com/builder-group/community/blob/develop/LICENSE">
+        <img src="https://img.shields.io/github/license/builder-group/community.svg?label=license&style=flat&colorA=293140&colorB=FDE200" alt="GitHub License"/>
+    </a>
+    <a href="https://www.npmjs.com/package/feature-core">
+        <img src="https://img.shields.io/bundlephobia/minzip/feature-core.svg?label=minzipped%20size&style=flat&colorA=293140&colorB=FDE200" alt="NPM bundle minzipped size"/>
+    </a>
+    <a href="https://www.npmjs.com/package/feature-core">
+        <img src="https://img.shields.io/npm/dt/feature-core.svg?label=downloads&style=flat&colorA=293140&colorB=FDE200" alt="NPM total downloads"/>
+    </a>
+    <a href="https://discord.gg/w4xE3bSjhQ">
+        <img src="https://img.shields.io/discord/795291052897992724.svg?label=&logo=discord&logoColor=000000&color=293140&labelColor=FDE200" alt="Join Discord"/>
+    </a>
+</p>
+
+> Status: Experimental
+
+`feature-core` is a small, typesafe foundation for building feature-based JavaScript and TypeScript libraries.
+
+- **Lightweight & Tree Shakable**: Object-based composition with no class hierarchy
+- **Modular & Extendable**: Add capabilities with `.with(feature())` instead of nested wrappers
+- **Typesafe**: Feature APIs and dependencies are tracked in TypeScript
+- **Author Friendly**: Custom features are plain objects created with `defineFeature()`
+- **Framework Agnostic**: Works for state containers, fetch clients, loggers, and other object-based libraries
+
+### 🌟 Motivation
+
+Feature-based libraries often repeat the same difficult parts: applying feature APIs, tracking installed features, validating dependencies, and preserving strong TypeScript inference. `feature-core` centralizes those mechanics so libraries can expose a consistent `.with(...)` extension model while feature authors only define a key, optional requirements, and an install function.
+
+## 📖 Usage
+
+Consumers compose features on a host object:
+
+```ts
+const state = createState(0)
+	.with(undoFeature(4))
+	.with(storageFeature(storage, 'count'))
+	.with(loggerFeature());
+
+state.undo();
+```
+
+Features can also be applied in order through one call:
+
+```ts
+const state = createState(0).with(
+	undoFeature(4),
+	storageFeature(storage, 'count'),
+	loggerFeature()
+);
+```
+
+The variadic form is typed in install order, so each feature is checked against the host produced by the features before it. Prefer chained `.with(...)` calls when a long feature list becomes harder to scan.
+
+## 📙 Building Libraries
+
+Libraries wrap their base object with `createFeatureHost()`.
+
+```ts
+import { createFeatureHost, type TFeatureHost } from 'feature-core';
+
+interface TCounterBase {
+	get: () => number;
+	set: (nextValue: number) => void;
+}
+
+type TCounterFeature = TResetFeature | TResetTwiceFeature;
+
+export type TCounter<GFeatures extends TCounterFeature[]> = TFeatureHost<
+	TCounterBase,
+	GFeatures
+>;
+
+export function createCounter(initialValue: number): TCounter<[]> {
+	let value = initialValue;
+
+	return createFeatureHost({
+		get() {
+			return value;
+		},
+		set(nextValue) {
+			value = nextValue;
+		}
+	});
+}
+
+interface TResetFeature {
+	key: 'reset';
+	api: {
+		reset: () => void;
+	};
+}
+
+interface TResetTwiceFeature {
+	key: 'resetTwice';
+	api: {
+		resetTwice: () => void;
+	};
+}
+```
+
+Feature hosts include `_features` metadata for `feature-core` internals. It is visible for transparency, marked internal in the type docs, and readonly in the public type. Prefer `hasFeature(host, key)` for app-level feature checks.
+
+### Type Names
+
+- `TFeature` is the runtime object returned by `defineFeature()`
+- `TInstalledFeature` is the `{ key, api }` contract once a feature is installed
+- `TDeclaredFeature` is a runtime feature with an explicit installed feature contract
+- `TFeatureHost` is the base object plus installed feature APIs and `.with()`
+
+## 📙 Creating Features
+
+Feature authors use `defineFeature()`.
+
+```ts
+import { defineFeature, type TDeclaredFeature } from 'feature-core';
+
+export function resetFeature(): TDeclaredFeature<TResetFeature> {
+	return defineFeature({
+		key: 'reset',
+		install<GFeatures extends TCounterFeature[]>(counter: TCounter<GFeatures>) {
+			const initialValue = counter.get();
+
+			return {
+				reset() {
+					counter.set(initialValue);
+				}
+			};
+		}
+	});
+}
+```
+
+The `TDeclaredFeature<TResetFeature>` return type is optional but recommended for reusable library features. It checks that the runtime key and returned API match the declared installed feature contract, and `.with()` carries that named feature into the host feature list.
+
+Prefer closing over the host passed to `install()` instead of relying on `this`. A returned method can still declare a `this` type, but closure-based methods are easier to write, refactor, and infer.
+
+### Dependent Features
+
+If a feature depends on another feature, declare the required installed feature contracts, runtime `requires`, and a constrained install host:
+
+```ts
+export function resetTwiceFeature(): TDeclaredFeature<TResetTwiceFeature, [TResetFeature]> {
+	return defineFeature({
+		key: 'resetTwice',
+		requires: ['reset'] as const,
+		install(counter: TCounter<[TResetFeature]>) {
+			return {
+				resetTwice() {
+					counter.reset();
+					counter.reset();
+				}
+			};
+		}
+	});
+}
+```
+
+`TDeclaredFeature<TFeature, [TDependency]>` and `requires` provide install-order validation. The constrained `install()` host lets the implementation use dependency APIs without casts. Using all three gives better errors for humans and agents.
+
+The second `TDeclaredFeature` generic lists required installed feature contracts. `feature-core` derives the required key tuple from those contracts and checks it against the runtime `requires` value.
+
+### API-less Features
+
+Some features only mutate internal configuration and do not expose new methods. Return an empty object for those features:
+
+```ts
+export function cacheFeature() {
+	return defineFeature({
+		key: 'cache',
+		install<GFeatures extends TFetchFeature[]>(client: TFetchClient<GFeatures>) {
+			client._config.requestMiddlewares.push(cacheMiddleware());
+			return {};
+		}
+	});
+}
+```
+
+## 🔍 Feature Checks
+
+Use `hasFeature()` for runtime checks:
+
+```ts
+if (hasFeature(counter, 'reset')) {
+	console.log('Reset is installed');
+}
+```
+
+Pass the feature type when you want TypeScript to narrow the API:
+
+```ts
+if (hasFeature<TResetFeature>(value, 'reset')) {
+	value.reset();
+}
+```
+
+## ❓ FAQ
+
+### Why features instead of plugins?
+
+`feature-core` composes typed capabilities directly onto a host object. "Feature" describes that narrower contract better than "plugin", which often implies discovery, lifecycle hooks, registries, or installable packages.
+
+### Can features overwrite existing properties?
+
+No. Feature keys must be unique per host, and returned API keys must not overwrite existing host properties. `feature-core` throws when a feature is installed twice, when required features are missing, or when a feature tries to overwrite an existing property.
+
+### Should features use `this`?
+
+Prefer closing over the host passed to `install()`. `this` methods can work, but they are easier to call incorrectly and harder for agents to author consistently.
+
+### What should feature authors remember?
+
+- Use a unique feature key
+- Declare `requires` for runtime dependencies
+- Type the `install()` host when the feature depends on another feature
+- Return only new API keys
+- Return `{}` for features that only mutate internal configuration
+- Prefer chained `.with(...)` calls for long feature lists

package/dist/cjs/index.js

@@ -0,0 +1 @@
+"use strict";function s(e){return w(e),Object.assign(e,{_features:[],with:a})}function u(e){var r;return{key:e.key,requires:(r=e.requires)!=null?r:[],install:e.install}}function i(e,r){f(e,r),c(e,r);const t=r.install(e);return l(e,r,t),Object.assign(e,t),e._features.push(r.key),e}function o(e,r){return typeof e!="object"||e==null||!("_features"in e)||!Array.isArray(e._features)||!("with"in e)||typeof e.with!="function"?!1:e._features.includes(r)}function a(...e){for(const r of e)i(this,r);return this}function f(e,r){const t=r.requires.find(n=>!e._features.includes(n));if(t!=null)throw new Error(`Feature "${r.key}" requires missing feature "${t}"`)}function c(e,r){if(e._features.includes(r.key))throw new Error(`Feature "${r.key}" is already installed`)}function l(e,r,t){for(const n of Reflect.ownKeys(t))if(n in e)throw new Error(`Feature "${r.key}" cannot overwrite existing property "${String(n)}"`)}function w(e){for(const r of y)if(r in e)throw new Error(`Feature host cannot overwrite existing property "${r}"`)}const y=["_features","with"];exports.createFeatureHost=s,exports.defineFeature=u,exports.hasFeature=o,exports.installFeature=i;

package/dist/esm/index.js

@@ -0,0 +1 @@
+function s(r){return w(r),Object.assign(r,{_features:[],with:a})}function o(r){var e;return{key:r.key,requires:(e=r.requires)!=null?e:[],install:r.install}}function i(r,e){f(r,e),c(r,e);const t=e.install(r);return l(r,e,t),Object.assign(r,t),r._features.push(e.key),r}function u(r,e){return typeof r!="object"||r==null||!("_features"in r)||!Array.isArray(r._features)||!("with"in r)||typeof r.with!="function"?!1:r._features.includes(e)}function a(...r){for(const e of r)i(this,e);return this}function f(r,e){const t=e.requires.find(n=>!r._features.includes(n));if(t!=null)throw new Error(`Feature "${e.key}" requires missing feature "${t}"`)}function c(r,e){if(r._features.includes(e.key))throw new Error(`Feature "${e.key}" is already installed`)}function l(r,e,t){for(const n of Reflect.ownKeys(t))if(n in r)throw new Error(`Feature "${e.key}" cannot overwrite existing property "${String(n)}"`)}function w(r){for(const e of y)if(e in r)throw new Error(`Feature host cannot overwrite existing property "${e}"`)}const y=["_features","with"];export{s as createFeatureHost,o as defineFeature,u as hasFeature,i as installFeature};

package/dist/types/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Adds feature metadata and `.with()` to a plain object.
+ *
+ * Mutates and returns the provided object.
+ */
+export declare function createFeatureHost<GBase extends object>(base: GBase): TFeatureHost<GBase, []>;
+/**
+ * Defines a composable feature that can be installed on a feature host.
+ */
+export declare function defineFeature<const GKey extends string, const GRequiredFeatureKeys extends readonly string[] = [], GInstall extends TFeatureInstall = TFeatureInstall>(options: TDefineFeatureOptions<GKey, GRequiredFeatureKeys, GInstall>): TFeature<GKey, GRequiredFeatureKeys, GInstall>;
+/**
+ * Installs one feature on a host.
+ *
+ * Mutates and returns the host. Throws when requirements are missing, the feature is already
+ * installed, or the feature API would overwrite an existing property.
+ */
+export declare function installFeature<GBase extends object, GFeatures extends TInstalledFeature[], GFeature extends TAnyFeature>(host: TFeatureHost<GBase, GFeatures>, feature: GFeature & TFeatureRequirementConstraint<GFeature, GFeatures> & TFeatureInstallConstraint<GFeature, TFeatureHost<GBase, GFeatures>>): TFeatureHost<GBase, TInstalledFeaturesAfter<GBase, GFeatures, GFeature>>;
+/**
+ * Checks whether a value is a feature host with a specific installed feature.
+ */
+export declare function hasFeature<GFeature extends TInstalledFeature>(host: unknown, key: GFeature['key']): host is TFeatureHost<object, [GFeature]>;
+export declare function hasFeature<GKey extends string>(host: unknown, key: GKey): host is TFeatureHost<object, [{
+    key: GKey;
+    api: object;
+}]>;
+export interface TDefineFeatureOptions<GKey extends string, GRequiredFeatureKeys extends readonly string[], GInstall extends TFeatureInstall> {
+    /**
+     * Unique feature key used for runtime dependency checks.
+     */
+    key: GKey;
+    /**
+     * Feature keys that must already be installed before this feature can be installed.
+     */
+    requires?: GRequiredFeatureKeys;
+    /**
+     * Adds behavior to the host and returns the public API exposed by this feature.
+     */
+    install: GInstall;
+}
+/**
+ * Runtime feature object created by `defineFeature()`.
+ */
+export interface TFeature<GKey extends string = string, GRequiredFeatureKeys extends readonly string[] = readonly string[], GInstall extends TFeatureInstall = TFeatureInstall, GInstalledFeature extends TInstalledFeature<GKey, object> = never> {
+    key: GKey;
+    requires: GRequiredFeatureKeys;
+    install: GInstall;
+    /**
+     * @internal Type-only link to the installed feature contract.
+     */
+    readonly __installedFeature?: GInstalledFeature;
+}
+/**
+ * Feature contract after a runtime feature has been installed on a host.
+ */
+export interface TInstalledFeature<GKey extends string = string, GApi extends object = object> {
+    key: GKey;
+    api: GApi;
+}
+export type TFeatureHost<GBase extends object, GFeatures extends TInstalledFeature[]> = Omit<GBase, keyof TFeatureHostApi<object, TInstalledFeature[]>> & TFeatureApis<GFeatures> & TFeatureHostApi<GBase, GFeatures>;
+export interface TFeatureHostApi<GBase extends object, GFeatures extends TInstalledFeature[]> {
+    /**
+     * @internal Feature metadata used by feature-core. Prefer `hasFeature()` for app code.
+     */
+    readonly _features: readonly TFeatureKeys<GFeatures>[];
+    /**
+     * Installs features on this host.
+     */
+    with: TWithFeatureMethod<GBase, GFeatures>;
+}
+export interface TWithFeatureMethod<GBase extends object, GFeatures extends TInstalledFeature[]> {
+    <const GFeaturesToInstall extends TAnyFeature[]>(...features: GFeaturesToInstall & TInstallableFeatures<GBase, GFeatures, GFeaturesToInstall>): TFeatureHost<GBase, TInstalledFeaturesAfterAll<GBase, GFeatures, GFeaturesToInstall>>;
+}
+export type TAnyFeature = TFeature<string, readonly string[], TFeatureInstall, TInstalledFeature<string, object>>;
+/**
+ * Runtime feature object with an explicit installed feature contract.
+ */
+export type TDeclaredFeature<GInstalledFeature extends TInstalledFeature, GRequiredInstalledFeatures extends readonly TInstalledFeature[] = [], GInstall extends TFeatureInstall<GInstalledFeature['api']> = TFeatureInstall<GInstalledFeature['api']>> = TFeature<GInstalledFeature['key'], TFeatureKeyTuple<GRequiredInstalledFeatures>, GInstall, GInstalledFeature>;
+/**
+ * Generic feature install function. The `never` host keeps unconstrained feature installs
+ * assignable while concrete features can still narrow the host parameter.
+ */
+export type TFeatureInstall<GApi extends object = object> = (host: never) => GApi;
+export type TInstalledFeaturesAfter<GBase extends object, GFeatures extends TInstalledFeature[], GFeature extends TAnyFeature> = [...GFeatures, TInstalledFeatureFrom<GFeature, TFeatureHost<GBase, GFeatures>>];
+export type TInstalledFeaturesAfterAll<GBase extends object, GFeatures extends TInstalledFeature[], GFeaturesToInstall extends TAnyFeature[]> = GFeaturesToInstall extends [
+    infer GFeature extends TAnyFeature,
+    ...infer GRestFeatures extends TAnyFeature[]
+] ? TInstalledFeaturesAfterAll<GBase, TInstalledFeaturesAfter<GBase, GFeatures, GFeature>, GRestFeatures> : GFeatures;
+export type TInstallableFeatures<GBase extends object, GFeatures extends TInstalledFeature[], GFeaturesToInstall extends TAnyFeature[]> = GFeaturesToInstall extends [
+    infer GFeature extends TAnyFeature,
+    ...infer GRestFeatures extends TAnyFeature[]
+] ? [
+    TInstallableFeature<GFeature, TFeatureHost<GBase, GFeatures>>,
+    ...TInstallableFeatures<GBase, TInstalledFeaturesAfter<GBase, GFeatures, GFeature>, GRestFeatures>
+] : [];
+export type TInstalledFeatureFrom<GFeature extends TAnyFeature, GHost extends TFeatureHost<object, TInstalledFeature[]>> = TDeclaredInstalledFeatureOf<GFeature> extends TInstalledFeature ? TDeclaredInstalledFeatureOf<GFeature> : TInstalledFeature<GFeature['key'], TFeatureApiOf<GFeature, GHost>>;
+export type TDeclaredInstalledFeatureOf<GFeature extends TAnyFeature> = GFeature extends TFeature<string, readonly string[], TFeatureInstall, infer GInstalledFeature> ? [GInstalledFeature] extends [never] ? undefined : GInstalledFeature : undefined;
+export type TFeatureApiOf<GFeature extends TAnyFeature, GHost extends TFeatureHost<object, TInstalledFeature[]>> = GFeature extends {
+    install: (host: GHost) => infer GApi;
+} ? GApi extends object ? GApi : object : object;
+export type TInstallableFeature<GFeature extends TAnyFeature, GHost extends TFeatureHost<object, TInstalledFeature[]>> = TFeatureRequirementConstraint<GFeature, TInstalledFeaturesOf<GHost>> & TFeatureInstallConstraint<GFeature, GHost>;
+export type TFeatureRequirementConstraint<GFeature extends TAnyFeature, GFeatures extends TInstalledFeature[]> = TMissingFeatureKeys<GFeatures, GFeature['requires']> extends never ? GFeature : TMissingFeatureError<TMissingFeatureKeys<GFeatures, GFeature['requires']>>;
+export type TFeatureInstallConstraint<GFeature extends TAnyFeature, GHost extends TFeatureHost<object, TInstalledFeature[]>> = GFeature extends {
+    install: (host: infer GInstallHost) => object;
+} ? [GInstallHost] extends [never] ? GFeature : GHost extends GInstallHost ? GFeature : TIncompatibleFeatureHostError : GFeature;
+export interface TMissingFeatureError<GMissingFeatures extends string> {
+    error: 'Missing required features';
+    missing: GMissingFeatures;
+}
+export interface TIncompatibleFeatureHostError {
+    error: 'Feature install host is incompatible';
+}
+export type TInstalledFeaturesOf<GHost> = GHost extends TFeatureHostApi<object, infer GFeatures> ? GFeatures : [];
+export type TFeatureKeys<GFeatures extends TInstalledFeature[]> = GFeatures[number]['key'];
+export type TFeatureKeyTuple<GFeatures extends readonly TInstalledFeature[]> = Readonly<{
+    [GIndex in keyof GFeatures]: GFeatures[GIndex] extends TInstalledFeature<infer GKey> ? GKey : never;
+}>;
+export type TMissingFeatureKeys<GFeatures extends TInstalledFeature[], GRequiredFeatureKeys extends readonly string[]> = Exclude<GRequiredFeatureKeys[number], TFeatureKeys<GFeatures>>;
+export type TFeatureApis<GFeatures extends TInstalledFeature[]> = TIntersectAll<{
+    [GIndex in keyof GFeatures]: GFeatures[GIndex] extends TInstalledFeature<string, infer GApi> ? GApi : object;
+}>;
+export type TIntersectAll<GValues> = GValues extends readonly [infer GFirst, ...infer GRest] ? GFirst & TIntersectAll<GRest> : object;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "feature-core",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Composable feature primitives for TypeScript libraries",
+  "keywords": [],
+  "homepage": "https://builder.group/?utm_source=package-json",
+  "bugs": {
+    "url": "https://github.com/builder-group/community/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/builder-group/community.git"
+  },
+  "license": "MIT",
+  "author": "@bennobuilder",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "source": "./src/index.ts",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@blgc/config": "0.0.42",
+    "rollup-presets": "0.0.27"
+  },
+  "size-limit": [
+    {
+      "path": "dist/esm/index.js"
+    }
+  ],
+  "scripts": {
+    "build": "shx rm -rf dist && rollup -c rollup.config.js",
+    "build:prod": "export NODE_ENV=production && pnpm build",
+    "clean": "shx rm -rf dist && shx rm -rf .turbo && shx rm -rf node_modules",
+    "install:clean": "pnpm run clean && pnpm install",
+    "lint": "eslint . --fix",
+    "publish:patch": "pnpm build:prod && pnpm version patch && pnpm publish --no-git-checks --access=public",
+    "size": "size-limit --why",
+    "start:dev": "tsc -w",
+    "test": "vitest run",
+    "test:types": "vitest run --typecheck.only",
+    "update:latest": "pnpm update --latest"
+  }
+}