ts-strategy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 eli0shin
+
+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,121 @@
+# ts-strategy
+
+Type-safe strategy pattern for TypeScript. Register named strategy variants and execute them with compile-time type safety.
+
+## Install
+
+```sh
+npm install ts-strategy
+```
+
+Requires TypeScript 5+.
+
+## Usage
+
+```ts
+import { createStrategy } from 'ts-strategy';
+
+const pricing = createStrategy(
+  { variant: 'flat', toExecute: (amount: number) => amount },
+  { variant: 'percentage', toExecute: (amount: number) => amount * 0.1 }
+);
+
+pricing.variant('flat').execute(100); // 100
+pricing.variant('percentage').execute(100); // 10
+```
+
+## API
+
+### `createStrategy(...config)`
+
+```ts
+function createStrategy<VariantId extends string, StrategyFn>(
+  ...config: { variant: VariantId | VariantId[]; toExecute: StrategyFn }[]
+): {
+  variant: (id: VariantId) => { execute: (...args) => ReturnType<StrategyFn> };
+};
+```
+
+Each config object maps one or more variant IDs to a `toExecute` function. Returns a strategy object with a `.variant(id).execute(...args)` chain.
+
+**Parameters**
+
+- `config` — Rest arguments. Each is an object with:
+  - `variant` — A string or array of strings identifying this variant.
+  - `toExecute` — The function to run when this variant is selected.
+
+**Returns** an object with:
+
+- `.variant(id)` — Selects a variant by ID. Returns an object with `.execute()`.
+- `.execute(...args)` — Calls the variant's `toExecute` function with the provided arguments and returns its result.
+
+## Type safety
+
+All `toExecute` functions must have compatible signatures. TypeScript infers a single shared function type from all config entries:
+
+```ts
+// This compiles — both functions take (name: string) and return string
+const strategy = createStrategy(
+  { variant: 'a', toExecute: (name: string) => `Hello ${name}` },
+  { variant: 'b', toExecute: (name: string) => `Goodbye ${name}` }
+);
+
+// This does NOT compile — (string) => string and (number) => number are incompatible
+const strategy = createStrategy(
+  { variant: 'a', toExecute: (x: string) => x },
+  { variant: 'b', toExecute: (x: number) => x } // Type error
+);
+```
+
+Variant IDs are narrowed to string literals. Passing an unregistered ID to `.variant()` is a compile-time error:
+
+```ts
+const strategy = createStrategy(
+  { variant: 'a', toExecute: () => 1 },
+  { variant: 'b', toExecute: () => 2 }
+);
+
+strategy.variant('a'); // OK
+strategy.variant('c'); // Type error: '"c"' is not assignable to '"a" | "b"'
+```
+
+## Array variants
+
+Map multiple variant IDs to the same function:
+
+```ts
+const strategy = createStrategy(
+  { variant: 'a', toExecute: () => 'solo' },
+  { variant: ['b', 'c'], toExecute: () => 'shared' }
+);
+
+strategy.variant('b').execute(); // 'shared'
+strategy.variant('c').execute(); // 'shared'
+```
+
+## Error handling
+
+Errors are deferred to `.execute()`. Calling `.variant(id)` with an unregistered ID does not throw — the error surfaces when `.execute()` is called:
+
+```ts
+// At runtime (e.g. via type assertion or dynamic input):
+strategy.variant('unknown' as any).execute();
+// throws Error: "No function defined for variant unknown"
+```
+
+## Duplicate variant IDs
+
+If the same variant ID appears in multiple config entries, the last one wins:
+
+```ts
+const strategy = createStrategy(
+  { variant: 'a', toExecute: () => 'first' },
+  { variant: 'a', toExecute: () => 'second' }
+);
+
+strategy.variant('a').execute(); // 'second'
+```
+
+## License
+
+MIT

package/dist/createStrategy.d.ts

@@ -0,0 +1,48 @@
+type StringOrStringArray<Value extends string> = Value | Value[];
+type AbstractStrategyFn = (...args: any[]) => any;
+type StrategyConfig<VariantId, StrategyFn> = {
+    variant: VariantId;
+    toExecute: StrategyFn;
+}[];
+type Strategy<VariantId, StrategyFn extends AbstractStrategyFn> = {
+    variant: (variant: VariantId) => StrategyVariant<StrategyFn>;
+};
+type StrategyVariant<StrategyFn extends AbstractStrategyFn> = {
+    execute: (...args: Parameters<StrategyFn>) => ReturnType<StrategyFn>;
+};
+/**
+ * `createStrategy` creates a strategy with different `variant`s and their corresponding functions `toExecute`.
+ *
+ * The `toExecute` function's arguments and return
+ * type must be compatible between all variants.
+ * This means that if 1 variant accepts 3 args and
+ * 1 only 2, all three args must be passed.
+ * Similarly, if 1 returns keys `a` and `b`, and 1
+ * only returns `a`, only `a` will be available in
+ * the result's type.
+ *
+ * @example
+ * // Define the strategy functions
+ * const strategyA = (name: string) => `Result from strategy A ${name}`;
+ * const strategyB = (name: string) => `Result from strategy B ${name}`;
+ *
+ * // Create the strategy with variants
+ * // In this example, variants 'B', and 'C' will have the same behavior
+ * // but variant 'A' will have a different behavior.
+ * const myStrategy = createStrategy(
+ *   { variant: 'A', toExecute: strategyA },
+ *   { variant: ['B', 'C'], toExecute: strategyB }
+ * );
+ *
+ * // Select and execute a strategy variant
+ * const resultA = myStrategy.variant('A').execute('Bob');
+ * console.log(resultA); // Output: 'Result from strategy A Bob'
+ *
+ * const resultB = myStrategy.variant('B').execute('Bob');
+ * console.log(resultB); // Output: 'Result from strategy B Bob'
+ *
+ * const resultC = myStrategy.variant('C').execute('Bob');
+ * console.log(resultC); // Output: 'Result from strategy B Bob'
+ */
+export declare function createStrategy<VariantId extends string, StrategyFn extends AbstractStrategyFn>(...config: StrategyConfig<StringOrStringArray<VariantId>, StrategyFn>): Strategy<VariantId, StrategyFn>;
+export {};

package/dist/index.cjs

@@ -0,0 +1,71 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  createStrategy: () => createStrategy
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/createStrategy.ts
+function createStrategy(...config) {
+  const variantsById = new Map;
+  config.forEach((variantConfig) => {
+    if (typeof variantConfig.variant === "string") {
+      variantsById.set(variantConfig.variant, variantConfig.toExecute);
+    } else {
+      variantConfig.variant.forEach((variantId) => {
+        variantsById.set(variantId, variantConfig.toExecute);
+      });
+    }
+  });
+  return {
+    variant: function variant(variantId) {
+      return {
+        execute: function execute(...args) {
+          const variantFn = variantsById.get(variantId);
+          if (!variantFn) {
+            throw new Error(`No function defined for variant ${variantId}`);
+          }
+          return variantFn(...args);
+        }
+      };
+    }
+  };
+}

package/dist/index.d.cts

@@ -0,0 +1 @@
+export * from './createStrategy';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './createStrategy';

package/dist/index.js

@@ -0,0 +1,29 @@
+// src/createStrategy.ts
+function createStrategy(...config) {
+  const variantsById = new Map;
+  config.forEach((variantConfig) => {
+    if (typeof variantConfig.variant === "string") {
+      variantsById.set(variantConfig.variant, variantConfig.toExecute);
+    } else {
+      variantConfig.variant.forEach((variantId) => {
+        variantsById.set(variantId, variantConfig.toExecute);
+      });
+    }
+  });
+  return {
+    variant: function variant(variantId) {
+      return {
+        execute: function execute(...args) {
+          const variantFn = variantsById.get(variantId);
+          if (!variantFn) {
+            throw new Error(`No function defined for variant ${variantId}`);
+          }
+          return variantFn(...args);
+        }
+      };
+    }
+  };
+}
+export {
+  createStrategy
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "ts-strategy",
+  "version": "1.0.0",
+  "description": "Type-safe strategy pattern for TypeScript. Register named strategy variants and execute them with compile-time type safety.",
+  "license": "MIT",
+  "author": "eli0shin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eli0shin/ts-strategy.git"
+  },
+  "homepage": "https://github.com/eli0shin/ts-strategy#readme",
+  "bugs": {
+    "url": "https://github.com/eli0shin/ts-strategy/issues"
+  },
+  "keywords": [
+    "strategy",
+    "typescript",
+    "type-safe"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build:esm && bun run build:cjs && bun run build:types",
+    "build:esm": "bun build src/index.ts --outdir dist --format esm --target node",
+    "build:cjs": "bun build src/index.ts --outfile dist/index.cjs --format cjs --target node",
+    "build:types": "tsc --project tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
+    "test": "vitest run --typecheck",
+    "type:check": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.7",
+    "@types/bun": "latest",
+    "@typescript-eslint/parser": "^8.50.1",
+    "@typescript-eslint/utils": "^8.50.1",
+    "eslint": "^9.39.2",
+    "eslint-for-ai": "^1.0.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.6.2",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^4.0.13"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,md,yml,yaml}": "prettier --write"
+  }
+}