@typed/guard 0.6.0 → 0.7.0

package/readme.md

@@ -0,0 +1,197 @@
+# @typed/guard
+
+[![npm version](https://badge.fury.io/js/%40typed%2Fguard.svg)](https://badge.fury.io/js/%40typed%2Fguard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A powerful, type-safe runtime validation library built on top of [Effect](https://effect.website/). `@typed/guard` provides a flexible and composable way to validate and transform data with full type inference and runtime safety.
+
+## Features
+
+- 🛡️ **Type-safe Guards**: Runtime validation with complete type inference
+- 🔄 **Effect Integration**: Seamless integration with Effect's ecosystem
+- 🎯 **Composable**: Rich set of combinators for building complex validations
+- 🌳 **Tree-shakeable**: Only import what you need
+- 🔍 **Schema Integration**: First-class support for Effect's Schema
+- ⚡ **Zero Dependencies**: Only requires Effect as a peer dependency
+
+## Installation
+
+```bash
+# Using npm
+npm install @typed/guard effect
+
+# Using yarn
+yarn add @typed/guard effect
+
+# Using pnpm
+pnpm add @typed/guard effect
+```
+
+## Quick Start
+
+```typescript
+import * as Guard from '@typed/guard'
+import { Effect, Option } from 'effect'
+
+// Simple number validation
+const isPositive = Guard.liftPredicate((n: number) => n > 0)
+
+// Usage
+const result = Effect.runSync(isPositive(5))  // Option.some(5)
+const invalid = Effect.runSync(isPositive(-1)) // Option.none()
+
+// Composing guards
+const toString = Guard.map(isPositive, n => n.toString())
+const result2 = Effect.runSync(toString(5)) // Option.some("5")
+```
+
+## Core Concepts
+
+### Guards
+
+A Guard is a function that takes an input and returns an `Effect` containing an `Option` of the output:
+
+```typescript
+type Guard<I, O = never, E = never, R = never> = 
+  (input: I) => Effect.Effect<Option.Option<O>, E, R>
+```
+
+- `I`: Input type
+- `O`: Output type
+- `E`: Error type
+- `R`: Required context
+
+### Key Operations
+
+#### Composition
+
+```typescript
+const numberToString = (n: number) =>
+  Effect.succeed(n > 5 ? Option.some(n.toString()) : Option.none())
+
+const stringToLength = (s: string) =>
+  Effect.succeed(s.length > 1 ? Option.some(s.length) : Option.none())
+
+// Compose them together
+const composed: Guard<number, number> = Guard.compose(isPositive, stringLength)
+```
+
+#### Filtering and Mapping
+
+```typescript
+// Filter values
+const evenNumbers = Guard.filter(isPositive, n => n % 2 === 0)
+
+// Map values with effects
+const asyncTransform = Guard.mapEffect(isPositive, n => 
+  Effect.promise(() => Promise.resolve(n * 2))
+)
+```
+
+#### Error Handling
+
+```typescript
+const withRecovery = Guard.catchAll(
+  failingGuard,
+  error => Effect.succeed(`Recovered from: ${error}`)
+)
+
+const withTaggedRecovery = Guard.catchTag(
+  failingGuard,
+  'ValidationError',
+  error => Effect.succeed(`Invalid input: ${error.message}`)
+)
+```
+
+#### Schema Integration
+
+```typescript
+import { Schema } from 'effect'
+
+const PersonSchema = Schema.struct({
+  name: Schema.string,
+  age: Schema.number
+})
+
+const personGuard = Guard.fromSchemaDecode(PersonSchema)
+```
+
+## Advanced Usage
+
+### Pattern Matching with `any`
+
+```typescript
+const numberOrString = Guard.any({
+  number: Guard.liftPredicate((n): n is number => typeof n === 'number'),
+  string: Guard.liftPredicate((s): s is string => typeof s === 'string')
+})
+
+// Returns: { _tag: 'number', value: 123 }
+Effect.runSync(numberOrString(123))
+
+// Returns: { _tag: 'string', value: 'hello' }
+Effect.runSync(numberOrString('hello'))
+```
+
+### Property Binding
+
+```typescript
+import { pipe } from 'effect'
+
+const complexGuard = pipe(
+  Guard.identity<number>,
+  Guard.bindTo('value'),
+  Guard.bind('asString', ({ value }) => 
+    Effect.succeedSome(value.toString())
+  ),
+  Guard.let('asBigInt', ({ asString }) => 
+    BigInt(asString)
+  )
+)
+
+// Returns: { value: 123, asString: '123', asBigInt: 123n }
+Effect.runSync(complexGuard(123))
+```
+
+### Creating Reusable Guards with `Guardable`
+
+The `Guardable` class allows you to create reusable guards as classes. This is particularly useful when you need to create guards that are also data structures
+
+```typescript
+import { Guardable, GUARDABLE } from '@typed/guard'
+import { Effect } from 'effect'
+
+// Create a guard that multiplies numbers by a configurable value
+class MultiplyGuard extends Guardable<number, number> {
+  constructor(readonly multiplier: number) {
+    super()
+  }
+
+  // Implement the GUARDABLE symbol to define the guard's behavior
+  [GUARDABLE] = (input: number) => 
+    Effect.succeedSome(input * this.multiplier)
+}
+
+// Create an instance with a specific multiplier
+const multiplyByThree = new MultiplyGuard(3)
+
+// Use it like a regular guard function
+Effect.runSync(multiplyByThree(4)) // Option.some(12)
+
+// It's pipeable too!
+
+const guard = multiplyByThree.pipe(
+  Guard.map(n => n.toString()),
+)
+
+Effect.runSync(guard(4)) // Option.some("12")
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © [Tylor Steinberger](https://github.com/TylorS)
+

package/src/ExtensibleFunction.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from '@effect/vitest'
+import { ExtensibleFunction } from './ExtensibleFunction.js'
+
+describe('ExtensibleFunction', () => {
+  it('should create a function that can be called normally', () => {
+    const add = new ExtensibleFunction((x: number) => x + 1)
+    expect(add(1)).toBe(2)
+  })
+
+  it('should allow extending the function with additional properties', () => {
+    class EnhancedFunction extends ExtensibleFunction<(x: number) => number> {
+      description: string
+
+      constructor(fn: (x: number) => number, description: string) {
+        super(fn)
+        this.description = description
+      }
+    }
+
+    const add = new EnhancedFunction((x: number) => x + 1, 'adds one')
+    expect(add(1)).toBe(2)
+    expect(add.description).toBe('adds one')
+  })
+
+  it('should maintain function properties like length and name', () => {
+    const namedFn = function addOne(x: number) {
+      return x + 1
+    }
+    const add = new ExtensibleFunction(namedFn)
+    expect(add.length).toBe(1)
+    expect(add.name).toBe('addOne')
+  })
+
+  it('should work with async functions', async () => {
+    const asyncAdd = new ExtensibleFunction(async (x: number) => {
+      return x + 1
+    })
+    expect(await asyncAdd(1)).toBe(2)
+  })
+
+  it('should preserve this context in methods', () => {
+    class Calculator extends ExtensibleFunction<(x: number) => number> {
+      private multiplier: number
+
+      constructor(multiplier: number) {
+        super((x: number) => this.multiply(x))
+        this.multiplier = multiplier
+      }
+
+      private multiply(x: number): number {
+        return x * this.multiplier
+      }
+    }
+
+    const calc = new Calculator(2)
+    expect(calc(3)).toBe(6)
+  })
+
+  it('should handle multiple arguments correctly', () => {
+    const add = new ExtensibleFunction((a: number, b: number) => a + b)
+    expect(add(1, 2)).toBe(3)
+  })
+
+  it('should work with generic functions', () => {
+    const identity = new ExtensibleFunction(<T>(x: T) => x)
+    expect(identity(42)).toBe(42)
+    expect(identity('test')).toBe('test')
+  })
+
+  it('should throw when constructed without arguments', () => {
+    expect(() => new ExtensibleFunction(undefined as any)).toThrow()
+  })
+
+  it('should maintain proper error stack traces', () => {
+    class Throws<E> extends ExtensibleFunction<(cause: E) => never> {
+      constructor() {
+        super((cause) => {
+          throw cause
+        })
+      }
+    }
+
+    const throws = new Throws<Error>()
+
+    try {
+      throws(new Error('test error'))
+    } catch (e) {
+      expect(e instanceof Error).toBe(true)
+      expect(e.stack).toBeDefined()
+      expect(e.message).toBe('test error')
+    }
+  })
+
+  it('should allow function composition', () => {
+    const add1 = new ExtensibleFunction((x: number) => x + 1)
+    const multiply2 = new ExtensibleFunction((x: number) => x * 2)
+    const composed = new ExtensibleFunction((x: number) => multiply2(add1(x)))
+    expect(composed(3)).toBe(8) // (3 + 1) * 2
+  })
+
+  it('should allow class decorator', () => {
+    
+  })
+})

package/src/ExtensibleFunction.ts

@@ -0,0 +1,8 @@
+function Extensible<I, O>(f: (input: I) => O): (input: I) => O {
+  return Object.setPrototypeOf(f, new.target.prototype)
+}
+Extensible.prototype = Function.prototype
+
+// Hack to make the type inference work
+export const ExtensibleFunction: new <F extends (...inputs: readonly any[]) => any>(f: F) => F =
+  Extensible as any

package/src/Guard.test.ts

@@ -0,0 +1,189 @@
+import { Effect, identity, Option, pipe, Predicate, Schema } from 'effect'
+import { describe, expect, it } from 'vitest'
+import * as Guard from './Guard'
+
+describe('Guard', () => {
+  // Helper function to run a guard and get the result
+  const runGuard = <I, O, E>(guard: Guard.Guard<I, O, E>, input: I) => Effect.runSync(guard(input))
+
+  describe('basic functionality', () => {
+    it('should create a basic guard that succeeds', () => {
+      const guard = (input: number): Effect.Effect<Option.Option<string>, never, never> =>
+        Effect.succeed(input > 5 ? Option.some(input.toString()) : Option.none())
+
+      expect(runGuard(guard, 10)).toEqual(Option.some('10'))
+      expect(runGuard(guard, 3)).toEqual(Option.none())
+    })
+  })
+
+  describe('compose', () => {
+    it('should compose two guards', () => {
+      const numberToString = (n: number) =>
+        Effect.succeed(n > 5 ? Option.some(n.toString()) : Option.none())
+      const stringToLength = (s: string) =>
+        Effect.succeed(s.length > 1 ? Option.some(s.length) : Option.none())
+
+      const composed = Guard.compose(numberToString, stringToLength)
+
+      expect(runGuard(composed, 10)).toEqual(Option.some(2))
+      expect(runGuard(composed, 3)).toEqual(Option.none())
+    })
+  })
+
+  describe('mapEffect and map', () => {
+    it('should map over guard results with Effect', () => {
+      const guard = (n: number) => Effect.succeed(n > 5 ? Option.some(n) : Option.none())
+      const mapped = Guard.mapEffect(guard, (n) => Effect.succeed(n * 2))
+
+      expect(runGuard(mapped, 10)).toEqual(Option.some(20))
+      expect(runGuard(mapped, 3)).toEqual(Option.none())
+    })
+
+    it('should map over guard results synchronously', () => {
+      const guard = (n: number) => Effect.succeed(n > 5 ? Option.some(n) : Option.none())
+      const mapped = Guard.map(guard, (n) => n * 2)
+
+      expect(runGuard(mapped, 10)).toEqual(Option.some(20))
+      expect(runGuard(mapped, 3)).toEqual(Option.none())
+    })
+  })
+
+  describe('tap', () => {
+    it('should perform side effects without modifying the result', () => {
+      let sideEffect = 0
+      const guard = (n: number) => Effect.succeed(n > 5 ? Option.some(n) : Option.none())
+      const tapped = Guard.tap(guard, (n) =>
+        Effect.sync(() => {
+          sideEffect = n
+        }),
+      )
+
+      expect(runGuard(tapped, 10)).toEqual(Option.some(10))
+      expect(sideEffect).toBe(10)
+
+      expect(runGuard(tapped, 3)).toEqual(Option.none())
+      expect(sideEffect).toBe(10) // Unchanged because guard returned None
+    })
+  })
+
+  describe('filterMap and filter', () => {
+    it('should filter and map values', () => {
+      const filtered = Guard.filterMap(Guard.identity<number>, (n) =>
+        n > 5 ? Option.some(n.toString()) : Option.none(),
+      )
+
+      expect(runGuard(filtered, 10)).toEqual(Option.some('10'))
+      expect(runGuard(filtered, 3)).toEqual(Option.none())
+    })
+
+    it('should filter values', () => {
+      const filtered = Guard.filter(Guard.identity<number>, (n) => n > 5)
+
+      expect(runGuard(filtered, 10)).toEqual(Option.some(10))
+      expect(runGuard(filtered, 3)).toEqual(Option.none())
+    })
+  })
+
+  describe('any', () => {
+    it('should match against multiple guards', () => {
+      const anyGuard = Guard.any({
+        number: Guard.liftPredicate(Predicate.isNumber),
+        string: Guard.liftPredicate(Predicate.isString),
+      })
+
+      expect(runGuard(anyGuard, 123)).toEqual(Option.some({ _tag: 'number', value: 123 }))
+      expect(runGuard(anyGuard, 'test')).toEqual(Option.some({ _tag: 'string', value: 'test' }))
+      expect(runGuard(anyGuard, true)).toEqual(Option.none())
+    })
+  })
+
+  describe('liftPredicate', () => {
+    it('should lift a predicate into a guard', () => {
+      const guard = Guard.liftPredicate(Predicate.isNumber)
+
+      expect(runGuard(guard, 123)).toEqual(Option.some(123))
+      expect(runGuard(guard, 'test')).toEqual(Option.none())
+    })
+  })
+
+  describe('error handling', () => {
+    describe('catchAll and catchAllCause', () => {
+      it('should catch errors', () => {
+        const failingGuard = (_: unknown) => Effect.fail('error')
+        const recovered = Guard.catchAll(failingGuard, (e) =>
+          Effect.succeed(['recovered:', e].join(' ')),
+        )
+
+        expect(runGuard(recovered, 123)).toEqual(Option.some('recovered: error'))
+      })
+
+      it('should catch error causes', () => {
+        const failingGuard = (_: unknown) => Effect.fail('error')
+        const recovered = Guard.catchAllCause(failingGuard, () =>
+          Effect.succeed('recovered from cause'),
+        )
+
+        expect(runGuard(recovered, 123)).toEqual(Option.some('recovered from cause'))
+      })
+    })
+
+    describe('catchTag', () => {
+      it('should catch specific error tags', () => {
+        type MyError = { _tag: 'MyError'; message: string }
+        const failingGuard = (_: unknown) =>
+          Effect.fail({ _tag: 'MyError', message: 'test error' } as MyError)
+        const recovered = Guard.catchTag(failingGuard, 'MyError', (e) =>
+          Effect.succeed(['recovered:', e.message].join(' ')),
+        )
+
+        expect(runGuard(recovered, 123)).toEqual(Option.some('recovered: test error'))
+      })
+    })
+  })
+
+  describe('schema integration', () => {
+    describe('fromSchemaDecode', () => {
+      it('should create a guard from a schema decoder', () => {
+        const guard = Guard.fromSchemaDecodeUnknown(Schema.Number)
+
+        expect(runGuard(guard, 123)).toEqual(Option.some(123))
+        expect(runGuard(guard, 'test')).toEqual(Option.none())
+      })
+    })
+
+    describe('fromSchemaEncode', () => {
+      it('should create a guard from a schema encoder', () => {
+        const guard = Guard.fromSchemaEncode(Schema.Number)
+
+        expect(runGuard(guard, 123)).toEqual(Option.some(123))
+        expect(runGuard(guard, 'test' as any)).toEqual(Option.none())
+      })
+    })
+  })
+
+  describe('property attachment', () => {
+    describe('attachProperty', () => {
+      it('should attach a property to the guarded value', () => {
+        const guard = (n: number) => Effect.succeed(Option.some({ value: n }))
+        const withProp = Guard.addTag(guard, 'number')
+
+        expect(runGuard(withProp, 123)).toEqual(Option.some({ _tag: 'number', value: 123 }))
+      })
+    })
+
+    describe('bind', () => {
+      it('should bind a new property based on the guarded value', () => {
+        const guard = pipe(
+          Guard.identity<number>,
+          Guard.bindTo('value'),
+          Guard.bind('asString', ({ value }) => Effect.succeedSome(value.toString())),
+          Guard.let('asBigInt', ({ asString }) => BigInt(asString)),
+        )
+
+        expect(runGuard(guard, 123)).toEqual(
+          Option.some({ value: 123, asString: '123', asBigInt: 123n }),
+        )
+      })
+    })
+  })
+})