nalloc 0.4.0 → 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/result.ts

@@ -106,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>

package/src/safe.ts

@@ -21,6 +21,7 @@ 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);
+}