typetify 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 typetify contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# typetify
+
+> Runtime TypeScript helpers — like Lodash, but TS-first.
+
+[![npm version](https://img.shields.io/npm/v/typetify.svg)](https://www.npmjs.com/package/typetify)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why typetify?
+
+TypeScript is powerful, but it doesn't protect you at runtime. Data from APIs, forms, localStorage, or JSON can break your app even when TypeScript says everything is fine.
+
+**typetify** fills this gap with:
+
+- ✅ **Runtime safety** — Guards and assertions that work at runtime
+- ✅ **Perfect types** — IntelliSense that actually helps
+- ✅ **Zero dependencies** — Lightweight and tree-shakable
+- ✅ **Boring API** — No magic, no config, just functions
+
+## Installation
+
+```bash
+npm install typetify
+```
+
+## Quick Start
+
+```typescript
+import { isDefined, pick, awaitTo, safeJsonParse } from 'typetify'
+
+// Filter null/undefined with proper types
+const items = [1, null, 2, undefined, 3]
+const defined = items.filter(isDefined) // number[]
+
+// Pick object keys (type-safe)
+const user = { id: 1, name: 'John', password: 'secret' }
+const safe = pick(user, ['id', 'name']) // { id: number, name: string }
+
+// Handle async errors without try/catch
+const [error, data] = await awaitTo(fetchUser(id))
+if (error) {
+  console.error('Failed:', error)
+  return
+}
+console.log(data.name)
+
+// Parse JSON safely
+const result = safeJsonParse<User>(jsonString)
+if (result.ok) {
+  console.log(result.data.name)
+} else {
+  console.error(result.error)
+}
+```
+
+## Modules
+
+### Core — Foundations
+
+```typescript
+import { isDefined, isNil, assert, assertDefined, fail, noop, identity, unreachable } from 'typetify/core'
+
+// isDefined — Filter null/undefined
+const items = [1, null, 2].filter(isDefined) // number[]
+
+// assert — Fail fast with type narrowing
+const user: User | null = getUser()
+assert(user, 'User not found')
+// user is now User
+
+// unreachable — Exhaustive switch statements
+switch (status) {
+  case 'pending': return handlePending()
+  case 'done': return handleDone()
+  default: unreachable(status)
+}
+```
+
+### Guards — Type Guards
+
+```typescript
+import { isObject, isString, isNumber, hasKey, hasKeys, isEmpty } from 'typetify/guards'
+
+// isObject — Check for objects (not arrays, not null)
+if (isObject(value)) {
+  // value is Record<string, unknown>
+}
+
+// hasKey — Safe property access
+if (hasKey(response, 'data')) {
+  console.log(response.data)
+}
+
+// isEmpty — Check for empty values
+isEmpty('') // true
+isEmpty([]) // true
+isEmpty({}) // true
+isEmpty(null) // true
+```
+
+### Object — Object Manipulation
+
+```typescript
+import { pick, omit, keysTyped, mapObject, get, set } from 'typetify/object'
+
+// pick/omit — Type-safe object manipulation
+const user = { id: 1, name: 'John', password: 'secret' }
+pick(user, ['id', 'name']) // { id: 1, name: 'John' }
+omit(user, ['password']) // { id: 1, name: 'John' }
+
+// keysTyped — Object.keys with proper types
+const keys = keysTyped(user) // ('id' | 'name' | 'password')[]
+
+// mapObject — Map over object values
+const prices = { apple: 1, banana: 2 }
+mapObject(prices, v => v * 2) // { apple: 2, banana: 4 }
+
+// get/set — Safe nested access (immutable)
+get(user, ['profile', 'name'])
+set(user, ['profile', 'age'], 30)
+```
+
+### Async — Async Utilities
+
+```typescript
+import { awaitTo, retry, sleep, withTimeout, debounce, throttle, parallel } from 'typetify/async'
+
+// awaitTo — No more try/catch
+const [error, user] = await awaitTo(fetchUser(id))
+
+// retry — Retry with backoff
+const data = await retry(() => fetchData(), {
+  attempts: 3,
+  delay: 1000,
+  backoff: 2,
+})
+
+// withTimeout — Add timeout to any promise
+const result = await withTimeout(fetchData(), 5000)
+
+// parallel — Concurrent execution with limit
+const results = await parallel(
+  urls.map(url => () => fetch(url)),
+  { concurrency: 3 }
+)
+
+// debounce/throttle
+const debouncedSearch = debounce(search, 300)
+const throttledScroll = throttle(onScroll, 100)
+```
+
+### Collection — Array Utilities
+
+```typescript
+import { unique, groupBy, partition, chunk, compact, sortBy, range } from 'typetify/collection'
+
+// unique — Remove duplicates
+unique([1, 2, 2, 3]) // [1, 2, 3]
+unique(users, u => u.id) // Unique by key
+
+// groupBy — Group by key
+groupBy(users, u => u.role)
+// { admin: [...], user: [...] }
+
+// partition — Split by predicate
+const [evens, odds] = partition([1, 2, 3, 4], n => n % 2 === 0)
+
+// chunk — Split into chunks
+chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+
+// compact — Remove null/undefined
+compact([1, null, 2, undefined]) // [1, 2]
+
+// sortBy — Sort by key
+sortBy(users, u => u.name)
+
+// range — Generate number ranges
+range(0, 5) // [0, 1, 2, 3, 4]
+```
+
+### Input — Parse External Data
+
+```typescript
+import { safeJsonParse, parseNumber, parseBoolean, parseDate, coerceArray, defaults } from 'typetify/input'
+
+// safeJsonParse — No more try/catch for JSON
+const result = safeJsonParse<User>(json)
+if (result.ok) {
+  console.log(result.data)
+}
+
+// parseNumber/parseBoolean/parseDate — Safe parsing
+parseNumber('42') // 42
+parseNumber('abc') // undefined
+parseBoolean('yes') // true
+parseDate('2024-01-15') // Date
+
+// coerceArray — Ensure array
+coerceArray('hello') // ['hello']
+coerceArray(['a', 'b']) // ['a', 'b']
+coerceArray(null) // []
+
+// defaults — With empty string handling
+defaults(null, 'fallback') // 'fallback'
+defaults('', 'fallback') // 'fallback'
+```
+
+### Flow — Functional Utilities
+
+```typescript
+import { pipe, tap, when, match, tryCatch, ifElse } from 'typetify/flow'
+
+// pipe — Chain transformations
+const result = pipe(
+  5,
+  n => n * 2,
+  n => n + 1,
+  n => `Result: ${n}`
+) // 'Result: 11'
+
+// tap — Side effects in a chain
+pipe(
+  data,
+  tap(console.log),
+  transform,
+)
+
+// match — Pattern matching
+const getDiscount = match<number, string>()
+  .with(n => n >= 100, () => '20% off')
+  .with(n => n >= 50, () => '10% off')
+  .otherwise(() => 'No discount')
+
+// tryCatch — Safe function execution
+const result = tryCatch(() => JSON.parse(input))
+if (result.ok) {
+  console.log(result.value)
+}
+```
+
+### DX — Developer Experience
+
+```typescript
+import { debug, invariant, assertNever, todo, measure } from 'typetify/dx'
+
+// debug — Log in a pipe chain
+pipe(data, debug('step 1'), transform, debug('step 2'))
+
+// invariant — Assert with descriptive errors
+invariant(user.id > 0, 'User ID must be positive')
+// Throws: Invariant violation: User ID must be positive
+
+// assertNever — Exhaustive checks
+function handle(action: Action) {
+  switch (action.type) {
+    case 'add': return handleAdd()
+    case 'remove': return handleRemove()
+    default: assertNever(action)
+  }
+}
+
+// todo — Mark unimplemented code
+function processPayment() {
+  todo('Implement payment processing')
+}
+
+// measure — Performance measurement
+const { result, duration } = measure(() => heavyComputation())
+console.log(`Took ${duration}ms`)
+```
+
+### Typed — Type Utilities
+
+```typescript
+import { defineConst, defineEnum, brand, type DeepPartial, type Merge } from 'typetify/typed'
+
+// defineConst — Frozen constants with literal types
+const STATUS = defineConst({
+  PENDING: 'pending',
+  ACTIVE: 'active',
+})
+// typeof STATUS.PENDING = 'pending' (not string)
+
+// defineEnum — Enum-like objects
+const Role = defineEnum(['admin', 'user', 'guest'] as const)
+// Role.admin = 'admin'
+
+// brand — Branded types for type safety
+type UserId = Brand<number, 'UserId'>
+type PostId = Brand<number, 'PostId'>
+
+function getUser(id: UserId) { ... }
+getUser(1 as UserId) // OK
+getUser(1 as PostId) // Error!
+
+// Type utilities
+type PartialUser = DeepPartial<User>
+type MergedConfig = Merge<DefaultConfig, UserConfig>
+```
+
+## Tree Shaking
+
+Import only what you need:
+
+```typescript
+// Import specific functions
+import { isDefined } from 'typetify/core'
+import { pick } from 'typetify/object'
+
+// Or import everything
+import { isDefined, pick, awaitTo } from 'typetify'
+```
+
+## Philosophy
+
+1. **Runtime first** — Types are great, but runtime safety matters more
+2. **No magic** — Every function does exactly what it says
+3. **Composable** — Small functions that work together
+4. **TypeScript-native** — Built for TS, not ported from JS
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## License
+
+MIT © typetify

package/dist/async/index.d.mts

@@ -0,0 +1,152 @@
+/**
+ * Wraps a promise to return a tuple of [error, result].
+ * Eliminates the need for try/catch blocks.
+ *
+ * @example
+ * const [error, user] = await awaitTo(fetchUser(id))
+ * if (error) {
+ *   console.error('Failed to fetch user:', error)
+ *   return
+ * }
+ * console.log(user.name)
+ */
+declare function awaitTo<T, E = Error>(promise: Promise<T>): Promise<[E, null] | [null, T]>;
+
+/**
+ * Returns a promise that resolves after the specified milliseconds.
+ *
+ * @example
+ * await sleep(1000) // wait 1 second
+ * console.log('Done waiting')
+ */
+declare function sleep(ms: number): Promise<void>;
+
+/**
+ * Wraps a promise with a timeout. Rejects if the promise doesn't resolve in time.
+ *
+ * @example
+ * const result = await withTimeout(fetchData(), 5000)
+ * // Throws if fetchData takes more than 5 seconds
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+
+interface RetryOptions {
+    /** Maximum number of attempts (default: 3) */
+    attempts?: number;
+    /** Delay between attempts in ms (default: 1000) */
+    delay?: number;
+    /** Multiply delay by this factor after each attempt (default: 1) */
+    backoff?: number;
+    /** Called when an attempt fails */
+    onRetry?: (error: Error, attempt: number) => void;
+}
+/**
+ * Retries a function until it succeeds or max attempts is reached.
+ *
+ * @example
+ * const data = await retry(() => fetchData(), {
+ *   attempts: 3,
+ *   delay: 1000,
+ *   backoff: 2,
+ * })
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Creates a debounced version of a function.
+ * The function will only be called after it stops being called for the specified delay.
+ *
+ * @example
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('Searching:', query)
+ * }, 300)
+ *
+ * debouncedSearch('h')
+ * debouncedSearch('he')
+ * debouncedSearch('hello') // Only this one executes after 300ms
+ */
+declare function debounce<T extends (...args: Parameters<T>) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+
+/**
+ * Creates a throttled version of a function.
+ * The function will only be called at most once per specified interval.
+ *
+ * @example
+ * const throttledScroll = throttle(() => {
+ *   console.log('Scroll event')
+ * }, 100)
+ *
+ * window.addEventListener('scroll', throttledScroll)
+ */
+declare function throttle<T extends (...args: Parameters<T>) => void>(fn: T, interval: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+
+/**
+ * Creates a function that can only be called once.
+ * Subsequent calls return the result of the first call.
+ *
+ * @example
+ * const initialize = once(() => {
+ *   console.log('Initializing...')
+ *   return { ready: true }
+ * })
+ *
+ * initialize() // logs 'Initializing...', returns { ready: true }
+ * initialize() // returns { ready: true } without logging
+ */
+declare function once<T extends (...args: Parameters<T>) => ReturnType<T>>(fn: T): T;
+
+/**
+ * Creates an async function that can only be called once.
+ * Subsequent calls return the same promise.
+ * Useful for initialization that should only happen once.
+ *
+ * @example
+ * const loadConfig = onceAsync(async () => {
+ *   const response = await fetch('/config')
+ *   return response.json()
+ * })
+ *
+ * // Both calls return the same promise
+ * const config1 = await loadConfig()
+ * const config2 = await loadConfig()
+ */
+declare function onceAsync<T>(fn: () => Promise<T>): () => Promise<T>;
+
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+}
+/**
+ * Creates a deferred promise that can be resolved or rejected externally.
+ *
+ * @example
+ * const deferred = defer<string>()
+ *
+ * setTimeout(() => {
+ *   deferred.resolve('Done!')
+ * }, 1000)
+ *
+ * const result = await deferred.promise
+ */
+declare function defer<T>(): Deferred<T>;
+
+/**
+ * Runs async functions in parallel with a concurrency limit.
+ *
+ * @example
+ * const urls = ['url1', 'url2', 'url3', 'url4', 'url5']
+ * const results = await parallel(
+ *   urls.map(url => () => fetch(url)),
+ *   { concurrency: 2 }
+ * )
+ */
+declare function parallel<T>(tasks: readonly (() => Promise<T>)[], options?: {
+    concurrency?: number;
+}): Promise<T[]>;
+
+export { type Deferred, type RetryOptions, awaitTo, debounce, defer, once, onceAsync, parallel, retry, sleep, throttle, withTimeout };

package/dist/async/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Wraps a promise to return a tuple of [error, result].
+ * Eliminates the need for try/catch blocks.
+ *
+ * @example
+ * const [error, user] = await awaitTo(fetchUser(id))
+ * if (error) {
+ *   console.error('Failed to fetch user:', error)
+ *   return
+ * }
+ * console.log(user.name)
+ */
+declare function awaitTo<T, E = Error>(promise: Promise<T>): Promise<[E, null] | [null, T]>;
+
+/**
+ * Returns a promise that resolves after the specified milliseconds.
+ *
+ * @example
+ * await sleep(1000) // wait 1 second
+ * console.log('Done waiting')
+ */
+declare function sleep(ms: number): Promise<void>;
+
+/**
+ * Wraps a promise with a timeout. Rejects if the promise doesn't resolve in time.
+ *
+ * @example
+ * const result = await withTimeout(fetchData(), 5000)
+ * // Throws if fetchData takes more than 5 seconds
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+
+interface RetryOptions {
+    /** Maximum number of attempts (default: 3) */
+    attempts?: number;
+    /** Delay between attempts in ms (default: 1000) */
+    delay?: number;
+    /** Multiply delay by this factor after each attempt (default: 1) */
+    backoff?: number;
+    /** Called when an attempt fails */
+    onRetry?: (error: Error, attempt: number) => void;
+}
+/**
+ * Retries a function until it succeeds or max attempts is reached.
+ *
+ * @example
+ * const data = await retry(() => fetchData(), {
+ *   attempts: 3,
+ *   delay: 1000,
+ *   backoff: 2,
+ * })
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Creates a debounced version of a function.
+ * The function will only be called after it stops being called for the specified delay.
+ *
+ * @example
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('Searching:', query)
+ * }, 300)
+ *
+ * debouncedSearch('h')
+ * debouncedSearch('he')
+ * debouncedSearch('hello') // Only this one executes after 300ms
+ */
+declare function debounce<T extends (...args: Parameters<T>) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+
+/**
+ * Creates a throttled version of a function.
+ * The function will only be called at most once per specified interval.
+ *
+ * @example
+ * const throttledScroll = throttle(() => {
+ *   console.log('Scroll event')
+ * }, 100)
+ *
+ * window.addEventListener('scroll', throttledScroll)
+ */
+declare function throttle<T extends (...args: Parameters<T>) => void>(fn: T, interval: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+
+/**
+ * Creates a function that can only be called once.
+ * Subsequent calls return the result of the first call.
+ *
+ * @example
+ * const initialize = once(() => {
+ *   console.log('Initializing...')
+ *   return { ready: true }
+ * })
+ *
+ * initialize() // logs 'Initializing...', returns { ready: true }
+ * initialize() // returns { ready: true } without logging
+ */
+declare function once<T extends (...args: Parameters<T>) => ReturnType<T>>(fn: T): T;
+
+/**
+ * Creates an async function that can only be called once.
+ * Subsequent calls return the same promise.
+ * Useful for initialization that should only happen once.
+ *
+ * @example
+ * const loadConfig = onceAsync(async () => {
+ *   const response = await fetch('/config')
+ *   return response.json()
+ * })
+ *
+ * // Both calls return the same promise
+ * const config1 = await loadConfig()
+ * const config2 = await loadConfig()
+ */
+declare function onceAsync<T>(fn: () => Promise<T>): () => Promise<T>;
+
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+}
+/**
+ * Creates a deferred promise that can be resolved or rejected externally.
+ *
+ * @example
+ * const deferred = defer<string>()
+ *
+ * setTimeout(() => {
+ *   deferred.resolve('Done!')
+ * }, 1000)
+ *
+ * const result = await deferred.promise
+ */
+declare function defer<T>(): Deferred<T>;
+
+/**
+ * Runs async functions in parallel with a concurrency limit.
+ *
+ * @example
+ * const urls = ['url1', 'url2', 'url3', 'url4', 'url5']
+ * const results = await parallel(
+ *   urls.map(url => () => fetch(url)),
+ *   { concurrency: 2 }
+ * )
+ */
+declare function parallel<T>(tasks: readonly (() => Promise<T>)[], options?: {
+    concurrency?: number;
+}): Promise<T[]>;
+
+export { type Deferred, type RetryOptions, awaitTo, debounce, defer, once, onceAsync, parallel, retry, sleep, throttle, withTimeout };

package/dist/async/index.js

@@ -0,0 +1,49 @@
+'use strict';
+
+var chunkGS3PP67B_js = require('../chunk-GS3PP67B.js');
+require('../chunk-PZ5AY32C.js');
+
+
+
+Object.defineProperty(exports, "awaitTo", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.awaitTo; }
+});
+Object.defineProperty(exports, "debounce", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.debounce; }
+});
+Object.defineProperty(exports, "defer", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.defer; }
+});
+Object.defineProperty(exports, "once", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.once; }
+});
+Object.defineProperty(exports, "onceAsync", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.onceAsync; }
+});
+Object.defineProperty(exports, "parallel", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.parallel; }
+});
+Object.defineProperty(exports, "retry", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.retry; }
+});
+Object.defineProperty(exports, "sleep", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.sleep; }
+});
+Object.defineProperty(exports, "throttle", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.throttle; }
+});
+Object.defineProperty(exports, "withTimeout", {
+  enumerable: true,
+  get: function () { return chunkGS3PP67B_js.withTimeout; }
+});
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/async/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}