errore 0.5.1 → 0.6.0

package/README.md

@@ -22,10 +22,10 @@ npm install errore
 ## Quick Start
 
 ```ts
-import { tryAsync, isError, TaggedError, matchError } from 'errore'
+import * as errore from 'errore'
 
 // Define typed errors
-class NotFoundError extends TaggedError('NotFoundError')<{
+class NotFoundError extends errore.TaggedError('NotFoundError')<{
   id: string
   message: string
 }>() {
@@ -34,19 +34,19 @@ class NotFoundError extends TaggedError('NotFoundError')<{
   }
 }
 
-class DbError extends TaggedError('DbError')<{
+class DbError extends errore.TaggedError('DbError')<{
   message: string
   cause: unknown
 }>() {}
 
 // Function returns Error | Value (no wrapper!)
 async function getUser(id: string): Promise<NotFoundError | DbError | User> {
-  const result = await tryAsync({
+  const result = await errore.tryAsync({
     try: () => db.query(id),
     catch: e => new DbError({ message: 'Query failed', cause: e })
   })
   
-  if (isError(result)) return result
+  if (errore.isError(result)) return result
   if (!result) return new NotFoundError({ id })
   
   return result
@@ -55,8 +55,8 @@ async function getUser(id: string): Promise<NotFoundError | DbError | User> {
 // Caller handles errors explicitly
 const user = await getUser('123')
 
-if (isError(user)) {
-  matchError(user, {
+if (errore.isError(user)) {
+  errore.matchError(user, {
     NotFoundError: e => console.log(`User ${e.id} not found`),
     DbError: e => console.log(`Database error: ${e.message}`)
   })
@@ -72,11 +72,11 @@ console.log(user.name)
 ### Type Guards
 
 ```ts
-import { isError, isOk } from 'errore'
+import * as errore from 'errore'
 
 const result: NetworkError | User = await fetchUser(id)
 
-if (isError(result)) {
+if (errore.isError(result)) {
   // result is NetworkError
   return result
 }
@@ -86,22 +86,22 @@ if (isError(result)) {
 ### Try Functions
 
 ```ts
-import { tryFn, tryAsync } from 'errore'
+import * as errore from 'errore'
 
 // Sync - wraps exceptions in UnhandledError
-const parsed = tryFn(() => JSON.parse(input))
+const parsed = errore.tryFn(() => JSON.parse(input))
 
 // Sync - with custom error type
-const parsed = tryFn({
+const parsed = errore.tryFn({
   try: () => JSON.parse(input),
   catch: e => new ParseError({ cause: e })
 })
 
 // Async
-const response = await tryAsync(() => fetch(url))
+const response = await errore.tryAsync(() => fetch(url))
 
 // Async - with custom error
-const response = await tryAsync({
+const response = await errore.tryAsync({
   try: () => fetch(url),
   catch: e => new NetworkError({ cause: e })
 })
@@ -110,19 +110,19 @@ const response = await tryAsync({
 ### Transformations
 
 ```ts
-import { map, mapError, andThen, tap } from 'errore'
+import * as errore from 'errore'
 
 // Transform value (if not error)
-const name = map(user, u => u.name)
+const name = errore.map(user, u => u.name)
 
 // Transform error
-const appError = mapError(dbError, e => new AppError({ cause: e }))
+const appError = errore.mapError(dbError, e => new AppError({ cause: e }))
 
 // Chain operations
-const posts = andThen(user, u => fetchPosts(u.id))
+const posts = errore.andThen(user, u => fetchPosts(u.id))
 
 // Side effects
-const logged = tap(user, u => console.log('Got user:', u.name))
+const logged = errore.tap(user, u => console.log('Got user:', u.name))
 ```
 
 ### Composing Operations
@@ -130,7 +130,7 @@ const logged = tap(user, u => console.log('Got user:', u.name))
 Chain multiple operations together:
 
 ```ts
-import { map, andThen, mapError, isError } from 'errore'
+import * as errore from 'errore'
 
 // Define operations that can fail
 function parseNumber(s: string): ValidationError | number { ... }
@@ -138,24 +138,24 @@ function validatePositive(n: number): ValidationError | number { ... }
 function divide(a: number, b: number): DivisionError | number { ... }
 
 // Compose with nested calls
-const result = andThen(
-  andThen(parseNumber(input), validatePositive),
+const result = errore.andThen(
+  errore.andThen(parseNumber(input), validatePositive),
   n => divide(100, n)
 )
 
 // Or step by step (often clearer)
 function calculate(input: string): ValidationError | DivisionError | number {
   const parsed = parseNumber(input)
-  if (isError(parsed)) return parsed
+  if (errore.isError(parsed)) return parsed
 
   const validated = validatePositive(parsed)
-  if (isError(validated)) return validated
+  if (errore.isError(validated)) return validated
 
   return divide(100, validated)
 }
 
 // Transform errors at the end
-const appResult = mapError(
+const appResult = errore.mapError(
   calculate(userInput),
   e => new AppError({ source: e._tag, message: e.message })
 )
@@ -164,23 +164,25 @@ const appResult = mapError(
 Real-world async composition:
 
 ```ts
+import * as errore from 'errore'
+
 async function processOrder(orderId: string): Promise<OrderError | Receipt> {
   const order = await fetchOrder(orderId)
-  if (isError(order)) return order
+  if (errore.isError(order)) return order
 
   const validated = validateOrder(order)
-  if (isError(validated)) return validated
+  if (errore.isError(validated)) return validated
 
   const payment = await processPayment(validated)
-  if (isError(payment)) return payment
+  if (errore.isError(payment)) return payment
 
   return generateReceipt(payment)
 }
 
 // Caller gets union of all possible errors
 const receipt = await processOrder('123')
-if (isError(receipt)) {
-  const message = matchError(receipt, {
+if (errore.isError(receipt)) {
+  const message = errore.matchError(receipt, {
     NotFoundError: e => `Order ${e.id} not found`,
     ValidationError: e => `Invalid: ${e.field}`,
     PaymentError: e => `Payment failed: ${e.reason}`,
@@ -193,37 +195,37 @@ if (isError(receipt)) {
 ### Extraction
 
 ```ts
-import { unwrap, unwrapOr, match, partition } from 'errore'
+import * as errore from 'errore'
 
 // Extract or throw
-const user = unwrap(result)
-const user = unwrap(result, 'Custom error message')
+const user = errore.unwrap(result)
+const user = errore.unwrap(result, 'Custom error message')
 
 // Extract or fallback
-const name = unwrapOr(result, 'Anonymous')
+const name = errore.unwrapOr(result, 'Anonymous')
 
 // Pattern match
-const message = match(result, {
+const message = errore.match(result, {
   ok: user => `Hello, ${user.name}`,
   err: error => `Failed: ${error.message}`
 })
 
 // Split array into [successes, errors]
-const [users, errors] = partition(results)
+const [users, errors] = errore.partition(results)
 ```
 
 ### Tagged Errors
 
 ```ts
-import { TaggedError, matchError, matchErrorPartial } from 'errore'
+import * as errore from 'errore'
 
 // Define errors with _tag discriminant
-class ValidationError extends TaggedError('ValidationError')<{
+class ValidationError extends errore.TaggedError('ValidationError')<{
   field: string
   message: string
 }>() {}
 
-class NetworkError extends TaggedError('NetworkError')<{
+class NetworkError extends errore.TaggedError('NetworkError')<{
   url: string
   message: string
 }>() {}
@@ -231,7 +233,7 @@ class NetworkError extends TaggedError('NetworkError')<{
 type AppError = ValidationError | NetworkError
 
 // Exhaustive matching (TypeScript ensures all cases handled)
-const message = matchError(error, {
+const message = errore.matchError(error, {
   ValidationError: e => `Invalid ${e.field}`,
   NetworkError: e => `Failed to fetch ${e.url}`
 })
@@ -240,20 +242,55 @@ console.log(message)
 // Handle plain Error with _ (underscore) handler
 function riskyOp(): ValidationError | Error { ... }
 const err = riskyOp()
-const msg = matchError(err, {
+const msg = errore.matchError(err, {
   ValidationError: e => `Invalid ${e.field}`,
   _: e => `Plain error: ${e.message}`  // catches non-tagged Error
 })
 
 // Partial matching with fallback
-const fallbackMsg = matchErrorPartial(error, {
+const fallbackMsg = errore.matchErrorPartial(error, {
   ValidationError: e => `Invalid ${e.field}`
 }, e => `Unknown error: ${e.message}`)
 console.log(fallbackMsg)
 
 // Type guards
 ValidationError.is(value)  // specific class
-TaggedError.is(value)      // any tagged error
+errore.TaggedError.is(value)      // any tagged error
+```
+
+### Custom Base Class
+
+Extend from your own base class to share functionality across all errors:
+
+```ts
+import * as errore from 'errore'
+
+// Custom base with shared functionality
+class AppError extends Error {
+  statusCode: number = 500
+  
+  report() {
+    sentry.captureException(this)
+  }
+}
+
+// Pass base class as second argument
+class NotFoundError extends errore.TaggedError('NotFoundError', AppError)<{
+  id: string
+  message: string
+}>() {
+  statusCode = 404
+}
+
+class ServerError extends errore.TaggedError('ServerError', AppError)<{
+  message: string
+}>() {}
+
+const err = new NotFoundError({ id: '123', message: 'User not found' })
+err.statusCode  // 404
+err.report()    // calls sentry
+err._tag        // 'NotFoundError'
+err instanceof AppError  // true
 ```
 
 ## How Type Safety Works
@@ -283,6 +320,8 @@ One of errore's best features: you can naturally combine error handling with opt
 In Rust, you'd need `Result<Option<T>, E>` or `Option<Result<T, E>>` and worry about the order. Here it's just a union:
 
 ```ts
+import * as errore from 'errore'
+
 // Result + Option in one natural type
 function findUser(id: string): NotFoundError | User | null {
   if (id === 'bad') return new NotFoundError({ id })
@@ -293,7 +332,7 @@ function findUser(id: string): NotFoundError | User | null {
 const user = findUser('123')
 
 // Handle error first
-if (isError(user)) {
+if (errore.isError(user)) {
   return user.message  // TypeScript: user is NotFoundError
 }
 
@@ -312,6 +351,8 @@ console.log(user.name)
 ### Works with `undefined` too
 
 ```ts
+import * as errore from 'errore'
+
 function lookup(key: string): NetworkError | string | undefined {
   if (key === 'fail') return new NetworkError({ url: '/api', message: 'Failed' })
   if (key === 'missing') return undefined
@@ -320,7 +361,7 @@ function lookup(key: string): NetworkError | string | undefined {
 
 const value = lookup('key')
 
-if (isError(value)) return value
+if (errore.isError(value)) return value
 
 // ?? works naturally with undefined
 const result = value ?? 'default'
@@ -331,6 +372,8 @@ const result = value ?? 'default'
 Even this works with full type inference:
 
 ```ts
+import * as errore from 'errore'
+
 function query(sql: string): ValidationError | { rows: string[] } | null | undefined {
   if (sql === 'invalid') return new ValidationError({ field: 'sql', message: 'Bad' })
   if (sql === 'empty') return null      // explicitly no data
@@ -340,7 +383,7 @@ function query(sql: string): ValidationError | { rows: string[] } | null | undef
 
 const result = query('SELECT *')
 
-if (isError(result)) {
+if (errore.isError(result)) {
   return result.field  // TypeScript: ValidationError
 }
 
@@ -377,6 +420,10 @@ With errore:
 | `Result<User, Error>` | `Error \| User` |
 | `Result<Option<T>, E>` | `Error \| T \| null` |
 
+## Import Style
+
+> **Note:** Always use `import * as errore from 'errore'` instead of named imports. This makes code easier to move between files, and more readable for people unfamiliar with errore since every function call is clearly namespaced (e.g. `errore.isError()` instead of just `isError()`).
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -25,20 +25,24 @@ type EnsureNotError<T> = T extends Error ? 'Error: Value type T cannot extend Er
 type AnyTaggedError = Error & {
     readonly _tag: string;
 };
+/**
+ * Any class that extends Error
+ */
+type ErrorClass = new (...args: any[]) => Error;
 /**
  * Instance type produced by TaggedError factory
  */
-type TaggedErrorInstance<Tag extends string, Props> = Error & {
+type TaggedErrorInstance<Tag extends string, Props, Base extends Error = Error> = Base & {
     readonly _tag: Tag;
     toJSON(): object;
 } & Readonly<Props>;
 /**
  * Class type produced by TaggedError factory
  */
-type TaggedErrorClass<Tag extends string, Props> = {
-    new (...args: keyof Props extends never ? [args?: {}] : [args: Props]): TaggedErrorInstance<Tag, Props>;
+type TaggedErrorClass<Tag extends string, Props, Base extends Error = Error> = {
+    new (...args: keyof Props extends never ? [args?: {}] : [args: Props]): TaggedErrorInstance<Tag, Props, Base>;
     /** Type guard for this error class */
-    is(value: unknown): value is TaggedErrorInstance<Tag, Props>;
+    is(value: unknown): value is TaggedErrorInstance<Tag, Props, Base>;
 };
 /**
  * Factory for tagged error classes with discriminated _tag property.
@@ -57,9 +61,27 @@ type TaggedErrorClass<Tag extends string, Props> = {
  * // Type guard
  * NotFoundError.is(err) // true
  * TaggedError.is(err)   // true (any tagged error)
+ *
+ * @example
+ * // With custom base class
+ * class AppError extends Error {
+ *   statusCode: number = 500
+ *   report() { console.log(this.message) }
+ * }
+ *
+ * class NotFoundError extends TaggedError("NotFoundError", AppError)<{
+ *   id: string;
+ *   message: string;
+ * }>() {
+ *   statusCode = 404
+ * }
+ *
+ * const err = new NotFoundError({ id: "123", message: "Not found" });
+ * err.statusCode // 404
+ * err.report()   // works
  */
 declare const TaggedError: {
-    <Tag extends string>(tag: Tag): <Props extends Record<string, unknown> = {}>() => TaggedErrorClass<Tag, Props>;
+    <Tag extends string, BaseClass extends ErrorClass = typeof Error>(tag: Tag, BaseClass?: BaseClass): <Props extends Record<string, unknown> = {}>() => TaggedErrorClass<Tag, Props, InstanceType<BaseClass>>;
     /** Type guard for any TaggedError instance */
     is(value: unknown): value is AnyTaggedError;
 };
@@ -111,7 +133,7 @@ declare function matchErrorPartial<E extends Error, R>(err: E, handlers: Partial
 declare const UnhandledError_base: TaggedErrorClass<"UnhandledError", {
     message: string;
     cause: unknown;
-}>;
+}, Error>;
 /**
  * Default error type when catching unknown exceptions.
  */

package/dist/index.d.ts

@@ -25,20 +25,24 @@ type EnsureNotError<T> = T extends Error ? 'Error: Value type T cannot extend Er
 type AnyTaggedError = Error & {
     readonly _tag: string;
 };
+/**
+ * Any class that extends Error
+ */
+type ErrorClass = new (...args: any[]) => Error;
 /**
  * Instance type produced by TaggedError factory
  */
-type TaggedErrorInstance<Tag extends string, Props> = Error & {
+type TaggedErrorInstance<Tag extends string, Props, Base extends Error = Error> = Base & {
     readonly _tag: Tag;
     toJSON(): object;
 } & Readonly<Props>;
 /**
  * Class type produced by TaggedError factory
  */
-type TaggedErrorClass<Tag extends string, Props> = {
-    new (...args: keyof Props extends never ? [args?: {}] : [args: Props]): TaggedErrorInstance<Tag, Props>;
+type TaggedErrorClass<Tag extends string, Props, Base extends Error = Error> = {
+    new (...args: keyof Props extends never ? [args?: {}] : [args: Props]): TaggedErrorInstance<Tag, Props, Base>;
     /** Type guard for this error class */
-    is(value: unknown): value is TaggedErrorInstance<Tag, Props>;
+    is(value: unknown): value is TaggedErrorInstance<Tag, Props, Base>;
 };
 /**
  * Factory for tagged error classes with discriminated _tag property.
@@ -57,9 +61,27 @@ type TaggedErrorClass<Tag extends string, Props> = {
  * // Type guard
  * NotFoundError.is(err) // true
  * TaggedError.is(err)   // true (any tagged error)
+ *
+ * @example
+ * // With custom base class
+ * class AppError extends Error {
+ *   statusCode: number = 500
+ *   report() { console.log(this.message) }
+ * }
+ *
+ * class NotFoundError extends TaggedError("NotFoundError", AppError)<{
+ *   id: string;
+ *   message: string;
+ * }>() {
+ *   statusCode = 404
+ * }
+ *
+ * const err = new NotFoundError({ id: "123", message: "Not found" });
+ * err.statusCode // 404
+ * err.report()   // works
  */
 declare const TaggedError: {
-    <Tag extends string>(tag: Tag): <Props extends Record<string, unknown> = {}>() => TaggedErrorClass<Tag, Props>;
+    <Tag extends string, BaseClass extends ErrorClass = typeof Error>(tag: Tag, BaseClass?: BaseClass): <Props extends Record<string, unknown> = {}>() => TaggedErrorClass<Tag, Props, InstanceType<BaseClass>>;
     /** Type guard for any TaggedError instance */
     is(value: unknown): value is AnyTaggedError;
 };
@@ -111,7 +133,7 @@ declare function matchErrorPartial<E extends Error, R>(err: E, handlers: Partial
 declare const UnhandledError_base: TaggedErrorClass<"UnhandledError", {
     message: string;
     cause: unknown;
-}>;
+}, Error>;
 /**
  * Default error type when catching unknown exceptions.
  */

package/dist/index.js

@@ -54,12 +54,13 @@ var isAnyTaggedError = (value) => {
   return value instanceof Error && "_tag" in value && typeof value._tag === "string";
 };
 var TaggedError = Object.assign(
-  (tag) => () => {
-    class Base extends Error {
+  (tag, BaseClass) => () => {
+    const ActualBase = BaseClass ?? Error;
+    class Tagged extends ActualBase {
       _tag = tag;
       /** Type guard for this error class */
       static is(value) {
-        return value instanceof Base;
+        return value instanceof Tagged;
       }
       constructor(args) {
         const message = args && "message" in args && typeof args.message === "string" ? args.message : void 0;
@@ -87,7 +88,7 @@ Caused by: ${indented}`;
         };
       }
     }
-    return Base;
+    return Tagged;
   },
   { is: isAnyTaggedError }
 );

package/dist/index.mjs

@@ -9,12 +9,13 @@ var isAnyTaggedError = (value) => {
   return value instanceof Error && "_tag" in value && typeof value._tag === "string";
 };
 var TaggedError = Object.assign(
-  (tag) => () => {
-    class Base extends Error {
+  (tag, BaseClass) => () => {
+    const ActualBase = BaseClass ?? Error;
+    class Tagged extends ActualBase {
       _tag = tag;
       /** Type guard for this error class */
       static is(value) {
-        return value instanceof Base;
+        return value instanceof Tagged;
       }
       constructor(args) {
         const message = args && "message" in args && typeof args.message === "string" ? args.message : void 0;
@@ -42,7 +43,7 @@ Caused by: ${indented}`;
         };
       }
     }
-    return Base;
+    return Tagged;
   },
   { is: isAnyTaggedError }
 );

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "errore",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Type-safe errors as values for TypeScript. Like Go, but with full type inference.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remorses/errore.git"
+  },
+  "homepage": "https://github.com/remorses/errore#readme",
+  "bugs": {
+    "url": "https://github.com/remorses/errore/issues"
+  },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",