nalloc 0.2.2 → 0.5.0

package/src/eslint.ts

@@ -0,0 +1,145 @@
+import { ESLintUtils, type TSESTree } from '@typescript-eslint/utils';
+import type * as ts from 'typescript';
+
+interface RuleDocs {
+  description: string;
+  requiresTypeChecking?: boolean;
+}
+
+const createRule = ESLintUtils.RuleCreator<RuleDocs>((name) => `https://github.com/3axap4eHko/nalloc#${name}`);
+
+const UNWRAP_NAMES: ReadonlySet<string> = new Set(['unwrap', 'unwrapErr', 'expect', 'expectErr']);
+const DEFAULT_MODULES: readonly string[] = ['nalloc', 'nalloc/safe', 'nalloc/unsafe', 'nalloc/result', 'nalloc/option'];
+const DEFAULT_TYPE_NAMES: readonly string[] = ['Result', 'Ok', 'Err', 'Option', 'Some', 'None'];
+
+function nallocTypeName(type: ts.Type, names: ReadonlySet<string>): string | undefined {
+  const direct = type.aliasSymbol?.getName();
+  if (direct !== undefined && names.has(direct)) {
+    return direct;
+  }
+  if (type.isUnion()) {
+    for (const member of type.types) {
+      const name = member.aliasSymbol?.getName();
+      if (name !== undefined && names.has(name)) {
+        return name;
+      }
+    }
+  }
+  return undefined;
+}
+
+const mustUse = createRule<[{ typeNames?: string[] }], 'mustUse'>({
+  name: 'must-use',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require Result and Option values to be handled instead of silently discarded',
+      requiresTypeChecking: true,
+    },
+    messages: {
+      mustUse: 'This {{name}} value is discarded. Handle it with match/unwrapOr/isErr/isNone, return it, or assign it.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: { typeNames: { type: 'array', items: { type: 'string' }, uniqueItems: true } },
+        additionalProperties: false,
+      },
+    ],
+    defaultOptions: [{}],
+  },
+  create(context, [options]) {
+    const names = new Set(options.typeNames ?? DEFAULT_TYPE_NAMES);
+    const services = ESLintUtils.getParserServices(context);
+    const check = (node: TSESTree.Expression): void => {
+      const name = nallocTypeName(services.getTypeAtLocation(node), names);
+      if (name !== undefined) {
+        context.report({ node, messageId: 'mustUse', data: { name } });
+      }
+    };
+    return {
+      'ExpressionStatement > CallExpression'(node: TSESTree.CallExpression): void {
+        check(node);
+      },
+      'ExpressionStatement > AwaitExpression'(node: TSESTree.AwaitExpression): void {
+        check(node);
+      },
+    };
+  },
+});
+
+const noUnwrap = createRule<[{ modules?: string[] }], 'noUnwrap'>({
+  name: 'no-unwrap',
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow unwrap and expect on Result and Option, which throw on failure',
+    },
+    messages: {
+      noUnwrap: '{{name}} throws on failure. Handle the error with match/unwrapOr/isErr, or turn this rule off in test files.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: { modules: { type: 'array', items: { type: 'string' }, uniqueItems: true } },
+        additionalProperties: false,
+      },
+    ],
+    defaultOptions: [{}],
+  },
+  create(context, [options]) {
+    const modules = new Set(options.modules ?? DEFAULT_MODULES);
+    const namespaceLocals = new Set<string>();
+    const directLocals = new Map<string, string>();
+    return {
+      ImportDeclaration(node: TSESTree.ImportDeclaration): void {
+        if (typeof node.source.value !== 'string' || !modules.has(node.source.value)) {
+          return;
+        }
+        for (const spec of node.specifiers) {
+          if (spec.type === 'ImportNamespaceSpecifier') {
+            namespaceLocals.add(spec.local.name);
+          } else if (spec.type === 'ImportSpecifier' && spec.imported.type === 'Identifier') {
+            const imported = spec.imported.name;
+            if (imported === 'Result' || imported === 'Option') {
+              namespaceLocals.add(spec.local.name);
+            } else if (UNWRAP_NAMES.has(imported)) {
+              directLocals.set(spec.local.name, imported);
+            }
+          }
+        }
+      },
+      CallExpression(node: TSESTree.CallExpression): void {
+        const callee = node.callee;
+        if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier' && callee.object.type === 'Identifier') {
+          if (UNWRAP_NAMES.has(callee.property.name) && namespaceLocals.has(callee.object.name)) {
+            context.report({ node: callee, messageId: 'noUnwrap', data: { name: callee.property.name } });
+          }
+          return;
+        }
+        if (callee.type === 'Identifier') {
+          const imported = directLocals.get(callee.name);
+          if (imported !== undefined) {
+            context.report({ node: callee, messageId: 'noUnwrap', data: { name: imported } });
+          }
+        }
+      },
+    };
+  },
+});
+
+export const rules = { 'must-use': mustUse, 'no-unwrap': noUnwrap };
+
+const plugin: { meta: { name: string }; rules: typeof rules; configs: Record<string, unknown> } = {
+  meta: { name: 'nalloc' },
+  rules,
+  configs: {},
+};
+
+plugin.configs.recommended = {
+  plugins: { nalloc: plugin },
+  rules: { 'nalloc/must-use': 'error', 'nalloc/no-unwrap': 'error' },
+};
+
+export { mustUse, noUnwrap };
+export default plugin;

package/src/http.ts

@@ -0,0 +1,42 @@
+import { err as ERR } from './types.js';
+import type { Ok, Result } from './types.js';
+
+/**
+ * Converts a fetch Response into a Result, treating a non-ok status as an Err.
+ * Native fetch only rejects on transport errors, never on 4xx/5xx; this closes that gap.
+ * The failed Response itself is the error - read its status, headers, or body from it.
+ * @param response - The Response to inspect
+ * @returns Ok(response) when response.ok, Err(response) otherwise
+ * @example
+ * import { Result } from 'nalloc';
+ * import { fromResponse } from 'nalloc/http';
+ * const res = Result.flatMap(await Result.fromPromise(fetch(url)), fromResponse);
+ */
+export function fromResponse(response: Response): Result<Response, Response> {
+  return response.ok ? (response as Ok<Response>) : ERR(response);
+}
+
+/**
+ * Runs fetch and forces every failure mode into the error channel.
+ * Ok means the request connected AND returned a 2xx status; a non-2xx Response
+ * becomes Err(response), and a transport failure becomes Err with the thrown
+ * value (per spec: TypeError on network/CORS errors, DOMException on abort/timeout).
+ * The body is never read - it stays available to the caller.
+ * @param input - The fetch input (URL or Request)
+ * @param init - Optional fetch init
+ * @returns Promise of Ok(response) for 2xx, Err otherwise
+ * @example
+ * import { fromFetch } from 'nalloc/http';
+ * const res = await fromFetch(url);
+ * // Ok(Response)      -> connected and 2xx
+ * // Err(Response)     -> reached the server, non-2xx
+ * // Err(TypeError)    -> network/CORS failure
+ * // Err(DOMException) -> aborted or timed out
+ */
+export async function fromFetch(input: string | URL | Request, init?: RequestInit): Promise<Result<Response, Response | TypeError | DOMException>> {
+  try {
+    return fromResponse(await fetch(input, init));
+  } catch (error) {
+    return ERR(error as TypeError | DOMException);
+  }
+}

package/src/nonempty.ts

@@ -0,0 +1,48 @@
+import { NONE } from './types.js';
+import type { Option, Some } from './types.js';
+
+/** An array proven to contain at least one element. The runtime value is a plain array. */
+export type NonEmptyArray<T> = [T, ...T[]];
+
+/** A readonly array proven to contain at least one element. The runtime value is a plain array. */
+export type ReadonlyNonEmptyArray<T> = readonly [T, ...T[]];
+
+/**
+ * Checks whether an array has at least one element.
+ * @param values - The array to check
+ * @returns true if the array is non-empty
+ * @example
+ * isNonEmpty([])     // false
+ * isNonEmpty([1])    // true
+ */
+export function isNonEmpty<T>(values: readonly T[]): values is ReadonlyNonEmptyArray<T> {
+  return values.length > 0;
+}
+
+/**
+ * Asserts that an array is non-empty, throwing otherwise.
+ * @param values - The array to check
+ * @param message - Custom error message
+ * @throws Error if the array is empty
+ * @example
+ * assertNonEmpty([1]) // passes
+ * assertNonEmpty([])  // throws Error
+ */
+export function assertNonEmpty<T>(values: readonly T[], message?: string): asserts values is ReadonlyNonEmptyArray<T> {
+  if (values.length === 0) {
+    throw new Error(message ?? 'Expected array to be non-empty');
+  }
+}
+
+/**
+ * Converts an array to an Option of a non-empty array. Returns the same array
+ * value when non-empty - no allocation or cloning.
+ * @param values - The array to convert
+ * @returns Some(values) typed as non-empty if length > 0, None otherwise
+ * @example
+ * fromArray([])     // None
+ * fromArray([1, 2]) // Some([1, 2]) with non-empty type
+ */
+export function fromArray<T>(values: readonly T[]): Option<ReadonlyNonEmptyArray<T>> {
+  return values.length > 0 ? (values as Some<ReadonlyNonEmptyArray<T>>) : NONE;
+}

package/src/option.ts

@@ -77,15 +77,14 @@ export function assertSome<T>(opt: Option<T>, message?: string): asserts opt is
  * runtime to preserve zero-allocation semantics. Use assertSome() if you
  * need runtime validation that a value is Some.
  *
- * @param _ - The value to assert as Option (not validated at runtime)
+ * @param value - The value to assert as Option (not validated at runtime)
  * @example
  * const value: number | null = getValue();
  * satisfiesOption(value); // Compiles, but no runtime check
  * // value is now typed as Option<number>
  */
-export function satisfiesOption<T>(_: Option<T> | T): asserts _ is Option<T> {
-  // Compile-time only - no runtime validation to preserve zero-allocation semantics.
-}
+// oxlint-disable-next-line no-unused-vars
+export function satisfiesOption<T>(value: Option<T> | T): asserts value is Option<T> {}
 
 /**
  * Maps and filters an iterable, collecting only Some values.

package/src/result.ts

@@ -1,5 +1,6 @@
 import { err as ERR, isOk, isErr, isSome, isNone, NONE, optionOf, isThenable } from './types.js';
 import type { Ok, Err, Result, Option, Widen, WidenNever, MaybePromise } from './types.js';
+import type { NonEmptyArray } from './nonempty.js';
 
 export type { Ok, Err, Result };
 export { isOk, isErr };
@@ -105,43 +106,6 @@ export async function fromPromise<T, E = unknown>(promise: Promise<T>, onError?:
   }
 }
 
-/** A validation issue from a Standard Schema validator. */
-export interface SchemaIssue {
-  readonly message: string;
-  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>;
-}
-
-/** Minimal Standard Schema v1 interface (duck-typed, no external dependency). */
-export interface StandardSchema<O = unknown> {
-  readonly '~standard': {
-    readonly validate: (value: unknown) => StandardSchemaResult<O> | Promise<StandardSchemaResult<O>>;
-  };
-}
-
-type StandardSchemaResult<O> = { readonly value: O; readonly issues?: undefined } | { readonly issues: ReadonlyArray<SchemaIssue> };
-
-function schemaResultToResult<O>(sr: StandardSchemaResult<O>): Result<O, readonly SchemaIssue[]> {
-  return sr.issues ? ERR(sr.issues) : (sr.value as Ok<O>);
-}
-
-/**
- * Validates a value against a Standard Schema and returns a Result.
- * Works with any Standard Schema v1 compliant library (Zod, Valibot, ArkType, etc.).
- * Returns synchronously if the schema validates synchronously.
- * @param schema - A Standard Schema v1 compliant schema
- * @param value - The value to validate
- * @returns Ok(parsed) if valid, Err(issues) if invalid
- * @example
- * import { z } from 'zod';
- * const result = fromSchema(z.string().email(), input);
- * // Result<string, readonly SchemaIssue[]>
- */
-export function fromSchema<O>(schema: StandardSchema<O>, value: unknown): Result<O, readonly SchemaIssue[]> | Promise<Result<O, readonly SchemaIssue[]>> {
-  const sr = schema['~standard'].validate(value);
-  if (isThenable(sr)) return sr.then(schemaResultToResult);
-  return schemaResultToResult(sr);
-}
-
 /**
  * Executes a function that may return sync or async, preserving sync execution when possible.
  * @param fn - Function that may return T or Promise<T>
@@ -659,7 +623,7 @@ export function collect<T, E>(results: Result<T, E>[]): Result<T[], E> {
  * collectAll([ok(1), ok(2)])           // Ok([1, 2])
  * collectAll([ok(1), err('a'), err('b')]) // Err(['a', 'b'])
  */
-export function collectAll<T, E>(results: Result<T, E>[]): Result<T[], E[]> {
+export function collectAll<T, E>(results: Result<T, E>[]): Result<T[], NonEmptyArray<E>> {
   const oks: T[] = [];
   const errs: E[] = [];
   for (let i = 0; i < results.length; i++) {
@@ -670,7 +634,7 @@ export function collectAll<T, E>(results: Result<T, E>[]): Result<T[], E[]> {
       errs.push(result.error);
     }
   }
-  return errs.length > 0 ? ERR(errs) : (oks as Ok<T[]>);
+  return errs.length > 0 ? ERR(errs as NonEmptyArray<E>) : (oks as Ok<T[]>);
 }
 
 /**
@@ -690,14 +654,14 @@ export function all<T, E>(results: Result<T, E>[]): Result<readonly Widen<T>[],
  * any([err('a'), ok(1), err('b')]) // Ok(1)
  * any([err('a'), err('b')])        // Err(['a', 'b'])
  */
-export function any<T, E>(results: Result<T, E>[]): Result<Widen<T>, WidenNever<E>[]> {
+export function any<T, E>(results: NonEmptyArray<Result<T, E>>): Result<Widen<T>, NonEmptyArray<WidenNever<E>>> {
   const errors: WidenNever<E>[] = [];
   for (let i = 0; i < results.length; i++) {
     const result = results[i];
     if (isOk(result)) return result as Ok<Widen<T>>;
     errors.push((result as Err<WidenNever<E>>).error);
   }
-  return ERR(errors);
+  return ERR(errors as NonEmptyArray<WidenNever<E>>);
 }
 
 /**
@@ -711,7 +675,7 @@ export function any<T, E>(results: Result<T, E>[]): Result<Widen<T>, WidenNever<
  */
 export function transpose<T, E>(result: Result<Option<T>, E>): Option<Result<T, E>> {
   if (isErr(result)) {
-    return ERR(result.error) as Option<Result<T, E>>;
+    return result as Option<Result<T, E>>;
   }
   const opt = result as Option<T>;
   return isNone(opt) ? NONE : (opt as unknown as Ok<T> as Option<Result<T, E>>);
@@ -909,11 +873,8 @@ export async function safeTryAsync<T>(fn: () => Promise<T>): Promise<Result<T, u
 }
 
 function* unwrapYield<T, E>(result: Result<T, E>): Generator<Err<E>, T> {
-  if (isErr(result)) {
-    yield result;
-    return undefined as never;
-  }
-  return result;
+  if (isErr(result)) yield result;
+  return result as T;
 }
 
 type Unwrapper = <T, E>(result: Result<T, E>) => Generator<Err<E>, T>;
@@ -934,7 +895,11 @@ type Unwrapper = <T, E>(result: Result<T, E>) => Generator<Err<E>, T>;
 export function gen<E, T>(fn: ($: Unwrapper) => Generator<Err<E>, T>): Result<T, E> {
   const iter = fn(unwrapYield);
   const step = iter.next();
-  if (!step.done) return step.value;
+  if (!step.done) {
+    // short-circuit abandons the generator mid-body; resume it so try/finally cleanup runs
+    iter.return(undefined as never);
+    return step.value;
+  }
   return step.value as Ok<T>;
 }
 
@@ -952,6 +917,10 @@ export function gen<E, T>(fn: ($: Unwrapper) => Generator<Err<E>, T>): Result<T,
 export async function genAsync<E, T>(fn: ($: Unwrapper) => AsyncGenerator<Err<E>, T>): Promise<Result<T, E>> {
   const iter = fn(unwrapYield);
   const step = await iter.next();
-  if (!step.done) return step.value;
+  if (!step.done) {
+    // short-circuit abandons the generator mid-body; resume it so try/finally cleanup runs
+    await iter.return(undefined as never);
+    return step.value;
+  }
   return step.value as Ok<T>;
 }

package/src/safe.ts

@@ -16,9 +16,12 @@ export type {
   MaybePromise,
 } from './types.js';
 export { safeTry, safeTryAsync, unwrap, gen, genAsync } from './result.js';
+export type { NonEmptyArray, ReadonlyNonEmptyArray } from './nonempty.js';
 export * as Option from './option.js';
 export * as Result from './result.js';
 export * as Iter from './iter.js';
+export * as NonEmpty from './nonempty.js';
+export * as Schema from './schema.js';
 
 /**
  * Threads a value through a sequence of unary functions, left to right.

package/src/schema.ts

@@ -0,0 +1,52 @@
+import { err as ERR, isThenable } from './types.js';
+import type { Ok, Result } from './types.js';
+
+/** A validation issue from a Standard Schema validator. */
+export interface SchemaIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>;
+}
+
+/** Minimal Standard Schema v1 interface (duck-typed, no external dependency). */
+export interface StandardSchema<O = unknown> {
+  readonly '~standard': {
+    readonly validate: (value: unknown) => StandardSchemaResult<O> | Promise<StandardSchemaResult<O>>;
+  };
+}
+
+type StandardSchemaResult<O> = { readonly value: O; readonly issues?: undefined } | { readonly issues: ReadonlyArray<SchemaIssue> };
+
+function schemaResultToResult<O>(sr: StandardSchemaResult<O>): Result<O, readonly SchemaIssue[]> {
+  return sr.issues ? ERR(sr.issues) : (sr.value as Ok<O>);
+}
+
+/**
+ * Validates a value against a Standard Schema and returns a Result.
+ * Works with any Standard Schema v1 compliant library (Zod, Valibot, ArkType, etc.).
+ * Returns synchronously if the schema validates synchronously.
+ * @param schema - A Standard Schema v1 compliant schema
+ * @param value - The value to validate
+ * @returns Ok(parsed) if valid, Err(issues) if invalid
+ * @example
+ * import { z } from 'zod';
+ * const result = fromSchema(z.string().email(), input);
+ * // Result<string, readonly SchemaIssue[]>
+ */
+export function fromSchema<O>(schema: StandardSchema<O>, value: unknown): Result<O, readonly SchemaIssue[]> | Promise<Result<O, readonly SchemaIssue[]>> {
+  const sr = schema['~standard'].validate(value);
+  if (isThenable(sr)) return sr.then(schemaResultToResult);
+  return schemaResultToResult(sr);
+}
+
+/**
+ * Binds a Standard Schema once and returns a reusable validator function.
+ * The partial-application form of fromSchema - validate many values against one schema.
+ * @param schema - A Standard Schema v1 compliant schema
+ * @returns A function that validates a value and returns a Result
+ * @example
+ * const parseUser = wrapSchema(userSchema);
+ * const result = parseUser(input); // Result<User, readonly SchemaIssue[]>
+ */
+export function wrapSchema<O>(schema: StandardSchema<O>): (value: unknown) => Result<O, readonly SchemaIssue[]> | Promise<Result<O, readonly SchemaIssue[]>> {
+  return (value) => fromSchema(schema, value);
+}