@konker.dev/neverthrow-r 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Type-level vocabulary for the package: the `ResultR` / `ResultAsyncR` shapes
+ * that add a *requirements* channel on top of `neverthrow`'s `Result` /
+ * `ResultAsync`, plus the helper types (`Scope`, `ExtendedScope`, `Simplify`)
+ * used by do-notation and intersection flattening.
+ *
+ * @remarks
+ * Most users only need {@link ResultR} and {@link ResultAsyncR}. The remaining
+ * exports are surfaced because the do-notation helpers (`bindR`, `bindAsyncR`)
+ * expose them in their return types, so consumers may encounter them in
+ * inferred types.
+ *
+ * Every operator across the package — sync, async, bridges, do — preserves the
+ * R/T/E shape and **intersects** the `R` channel across composed steps
+ * (`R1 & R2`), so requirements accumulate as a chain is built.
+ *
+ * @example
+ * Lift a value, transform it, accumulate requirements, then provide them:
+ *
+ * ```ts
+ * import { okR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThen, map } from '@konker.dev/neverthrow-r/sync';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ * import { provide } from '@konker.dev/neverthrow-r/provide';
+ * import type { ResultR } from '@konker.dev/neverthrow-r/types';
+ *
+ * type WithMultiplier = { multiplier: number };
+ *
+ * const scaled = (n: number): ResultR<WithMultiplier, number, never> =>
+ *   (r) => okR<number>(n * r.multiplier)(undefined);
+ *
+ * const program = pipe(
+ *   okR<number>(2),
+ *   map((n) => n + 1),
+ *   andThen(scaled),
+ * );
+ *
+ * provide(program, { multiplier: 10 }); // Ok(30)
+ * ```
+ *
+ * @module
+ */
+import type { Result, ResultAsync } from 'neverthrow';
+/**
+ * A `Result<T, E>` that requires an environment `R` to produce.
+ *
+ * @remarks
+ * `ResultR<R, T, E>` is structurally `(r: R) => Result<T, E>`. The `R` channel
+ * is the third dimension this package adds on top of `neverthrow`: it makes
+ * dependencies (database handles, config, clocks, …) explicit in the type
+ * rather than implicit in the closure.
+ *
+ * Use `unknown` for `R` when no environment is required (most often via the
+ * default on constructors like {@link okR}).
+ *
+ * Composition operators in {@link sync} and {@link do} intersect `R` across
+ * steps, so `R1 & R2 & R3` falls out of `andThen`-style chains automatically.
+ *
+ * @typeParam R - The requirements (environment) the value depends on.
+ * @typeParam T - The success type.
+ * @typeParam E - The error type.
+ *
+ * @example
+ * ```ts
+ * import type { ResultR } from '@konker.dev/neverthrow-r/types';
+ * import { ok } from 'neverthrow';
+ *
+ * type Deps = { now: () => Date };
+ *
+ * const currentYear: ResultR<Deps, number, never> =
+ *   (r) => ok(r.now().getFullYear());
+ * ```
+ *
+ * @see {@link ResultAsyncR} for the async sibling.
+ * @see {@link provide} for supplying the environment.
+ */
+export type ResultR<R, T, E> = (r: R) => Result<T, E>;
+/**
+ * A `ResultAsync<T, E>` that requires an environment `R` to produce.
+ *
+ * @remarks
+ * The async sibling of {@link ResultR}. Structurally `(r: R) => ResultAsync<T, E>`.
+ * Combine sync and async values in one pipeline via the {@link bridges} module.
+ *
+ * @typeParam R - The requirements (environment) the value depends on.
+ * @typeParam T - The success type.
+ * @typeParam E - The error type.
+ *
+ * @example
+ * ```ts
+ * import type { ResultAsyncR } from '@konker.dev/neverthrow-r/types';
+ * import { okAsync } from 'neverthrow';
+ *
+ * type Deps = { fetch: (url: string) => Promise<unknown> };
+ *
+ * const fetchJson: (url: string) => ResultAsyncR<Deps, unknown, never> =
+ *   (url) => (r) => okAsync(undefined).map(() => r.fetch(url));
+ * ```
+ *
+ * @see {@link ResultR} for the sync version.
+ */
+export type ResultAsyncR<R, T, E> = (r: R) => ResultAsync<T, E>;
+/**
+ * Flattens an intersection type into a single record so it renders nicely in
+ * inferred type displays and tooltips.
+ *
+ * @remarks
+ * Used internally where a chain has accumulated `R1 & R2 & R3 & …` and a
+ * cleaner display is desired (e.g. {@link provideSome}'s return type). Has no
+ * runtime effect.
+ *
+ * @typeParam T - The type to flatten.
+ *
+ * @example
+ * ```ts
+ * import type { Simplify } from '@konker.dev/neverthrow-r/types';
+ *
+ * type A = { a: number };
+ * type B = { b: string };
+ * type Combined = Simplify<A & B>; // { a: number; b: string }
+ * ```
+ */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * A record-shaped scope keyed by string field names, used by do-notation to
+ * accumulate intermediate values across a chain of `bindR` / `bindAsyncR`
+ * steps.
+ *
+ * @typeParam Keys - The union of string keys currently in the scope.
+ *
+ * @example
+ * ```ts
+ * import type { Scope } from '@konker.dev/neverthrow-r/types';
+ *
+ * type S = Scope<'user' | 'config'>;
+ * // { user: unknown; config: unknown }
+ * ```
+ *
+ * @see {@link ExtendedScope} for the type-level "add a field" operation.
+ */
+export type Scope<Keys extends string> = Record<Keys, unknown>;
+/**
+ * Adds a typed field `N: A` to an existing scope `S`, preserving the existing
+ * fields' types. Distributive over unions in `S`.
+ *
+ * @remarks
+ * This is the type-level operation behind {@link bindR}: it computes the
+ * record shape *after* a new field has been bound, with the new field's type
+ * `A` slotted in and existing fields untouched.
+ *
+ * @typeParam S - The existing scope record.
+ * @typeParam N - The string-literal name of the field being added.
+ * @typeParam A - The type of the newly bound value.
+ *
+ * @example
+ * ```ts
+ * import type { ExtendedScope } from '@konker.dev/neverthrow-r/types';
+ *
+ * type S0 = { user: { id: number } };
+ * type S1 = ExtendedScope<S0, 'role', 'admin' | 'guest'>;
+ * // { user: { id: number }; role: 'admin' | 'guest' }
+ * ```
+ *
+ * @see {@link bindR}
+ */
+export type ExtendedScope<S extends object, N extends string, A> = S extends unknown ? {
+    [K in keyof S | N]: K extends N ? A : K extends keyof S ? S[K] : never;
+} : never;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,KAAK,CAAC,IAAI,SAAS,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,CAAC,SAAS,OAAO,GAChF;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK;CACvE,GACD,KAAK,CAAC"}

package/dist/types.js

@@ -0,0 +1,44 @@
+/**
+ * Type-level vocabulary for the package: the `ResultR` / `ResultAsyncR` shapes
+ * that add a *requirements* channel on top of `neverthrow`'s `Result` /
+ * `ResultAsync`, plus the helper types (`Scope`, `ExtendedScope`, `Simplify`)
+ * used by do-notation and intersection flattening.
+ *
+ * @remarks
+ * Most users only need {@link ResultR} and {@link ResultAsyncR}. The remaining
+ * exports are surfaced because the do-notation helpers (`bindR`, `bindAsyncR`)
+ * expose them in their return types, so consumers may encounter them in
+ * inferred types.
+ *
+ * Every operator across the package — sync, async, bridges, do — preserves the
+ * R/T/E shape and **intersects** the `R` channel across composed steps
+ * (`R1 & R2`), so requirements accumulate as a chain is built.
+ *
+ * @example
+ * Lift a value, transform it, accumulate requirements, then provide them:
+ *
+ * ```ts
+ * import { okR } from '@konker.dev/neverthrow-r/constructors';
+ * import { andThen, map } from '@konker.dev/neverthrow-r/sync';
+ * import { pipe } from '@konker.dev/neverthrow-r/pipe';
+ * import { provide } from '@konker.dev/neverthrow-r/provide';
+ * import type { ResultR } from '@konker.dev/neverthrow-r/types';
+ *
+ * type WithMultiplier = { multiplier: number };
+ *
+ * const scaled = (n: number): ResultR<WithMultiplier, number, never> =>
+ *   (r) => okR<number>(n * r.multiplier)(undefined);
+ *
+ * const program = pipe(
+ *   okR<number>(2),
+ *   map((n) => n + 1),
+ *   andThen(scaled),
+ * );
+ *
+ * provide(program, { multiplier: 10 }); // Ok(30)
+ * ```
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG"}

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@konker.dev/neverthrow-r",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "Konrad Markus <mail@konker.dev>",
+  "license": "ISC",
+  "description": "Extension for neverthrow to add a requirements/dependencies channel",
+  "homepage": "https://konker.dev/",
+  "keywords": [
+    "node",
+    "neverthrow",
+    "dependency",
+    "typescript",
+    "functional-programming"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konker/konker.dev/packages/neverthrow-r"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./async": {
+      "types": "./dist/async.d.ts",
+      "import": "./dist/async.js"
+    },
+    "./bridges": {
+      "types": "./dist/bridges.d.ts",
+      "import": "./dist/bridges.js"
+    },
+    "./constructors": {
+      "types": "./dist/constructors.d.ts",
+      "import": "./dist/constructors.js"
+    },
+    "./do": {
+      "types": "./dist/do.d.ts",
+      "import": "./dist/do.js"
+    },
+    "./pipe": {
+      "types": "./dist/pipe.d.ts",
+      "import": "./dist/pipe.js"
+    },
+    "./provide": {
+      "types": "./dist/provide.d.ts",
+      "import": "./dist/provide.js"
+    },
+    "./sync": {
+      "types": "./dist/sync.d.ts",
+      "import": "./dist/sync.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/**/*.test.*"
+  ],
+  "main": "dist/index.js",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@effect/language-service": "^0.86.1",
+    "@eslint/compat": "^2.0.1",
+    "@eslint/js": "^9.39.2",
+    "@konker.dev/common-config": "^0.8.0",
+    "@types/node": "^25.8.0",
+    "@vitest/coverage-istanbul": "^4.1.6",
+    "aws-sdk-client-mock": "^4.1.0",
+    "aws-sdk-client-mock-vitest": "^7.0.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-fp": "^2.3.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-sort-destructure-keys": "^2.0.0",
+    "leasot": "^14.4.0",
+    "madge": "^8.0.0",
+    "prettier": "^3.8.3",
+    "tsx": "^4.22.1",
+    "type-coverage": "^2.29.7",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.4.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0",
+    "vitest": "^4.1.6"
+  },
+  "dependencies": {
+    "neverthrow": "^8.2.0"
+  },
+  "scripts": {
+    "test": "vitest run --coverage",
+    "clean": "rm -rf dist && rm -f tsconfig.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "build": "pnpm run clean && tsc",
+    "type-coverage-check": "type-coverage --detail --at-least 97",
+    "circular-check": "madge --extensions ts --circular --no-color --no-spinner --warning src",
+    "eslint-check": "eslint --max-warnings=0 '**/*.{ts,js,json}'",
+    "eslint-fix": "npx eslint --fix||true",
+    "generated-exports-check": "npx --package=@konker.dev/common-config generate-exports-verify `pwd`",
+    "docs-generate": "typedoc",
+    "generated-docs-check": "pnpm run docs-generate && git diff --exit-code docs/reference",
+    "examples-check": "node scripts/check-examples.mjs",
+    "exports-check": "NPM_CONFIG_CACHE=.npm-cache attw --pack . --ignore-rules=cjs-resolves-to-esm --profile=esm-only",
+    "fixme-check": "leasot --exit-nicely --skip-unsupported src",
+    "prettier-check": "npx prettier --check --ignore-path .gitignore --ignore-path .prettierignore '**/*.{css,html,js,ts,json,md,yaml,yml}'",
+    "prettier-fix": "pnpm run prettier-check --write",
+    "lint-check": "pnpm run eslint-check && pnpm run prettier-check && pnpm run circular-check && pnpm run fixme-check",
+    "lint-fix": "pnpm run eslint-fix && pnpm run prettier-fix",
+    "pre-push": "pnpm run lint-check && pnpm run typecheck",
+    "codecov": "npx --package=@konker.dev/common-config codecov-upload `pwd` '@konker.dev/neverthrow-r'",
+    "ci": "pnpm run lint-check && pnpm run typecheck && pnpm run type-coverage-check && pnpm run test && pnpm run build && pnpm run generated-exports-check && pnpm run generated-docs-check && pnpm run examples-check && pnpm run exports-check && pnpm run fixme-check",
+    "cd": "pnpm run build && npx --package=@konker.dev/common-config npm-publish-if-version-not-exists `pwd`"
+  }
+}