@typed/async-data 0.11.0 → 0.13.0

package/dist/TypeId.js

@@ -0,0 +1,8 @@
+/**
+ * @since 1.0.0
+ */
+/**
+ * @since 1.0.0
+ */
+export const AsyncDataTypeId = Symbol.for('@typed/async-data/AsyncData');
+//# sourceMappingURL=TypeId.js.map

package/dist/TypeId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeId.js","sourceRoot":"","sources":["../src/TypeId.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAA"}

package/dist/_internal.d.ts

@@ -0,0 +1,16 @@
+import { type Effect, Equal, Hash, Schema, type SchemaAST } from 'effect';
+/**
+ * Constructs the same interface as `Schema.Struct`, but with the ability to
+ * wrap it in Data.struct to ensure we can hash the struct.
+ */
+export declare function DataStruct<Fields extends Schema.Struct.Fields>(fields: Fields): Schema.Struct<Fields>;
+export type LiteralWithDefault<K extends string, A extends SchemaAST.LiteralValue> = Schema.PropertySignature<':', A, K, ':', A, true, never>;
+export declare function LiteralWithDefault<K extends string>(): <const A extends SchemaAST.LiteralValue>(value: A) => LiteralWithDefault<K, A>;
+export type DataEffect<F extends Record<string, any>, A, E = never, R = never> = Effect.Effect<A, E, R> & F & Hash.Hash & Equal.Equal;
+export interface DataEffectClass<Tag extends string> {
+    readonly _tag: Tag;
+    new <Fields extends Record<string, any>, A = never, E = never, R = never>(fields: Fields, commit: Effect.Effect<A, E, R>): DataEffect<Fields & {
+        readonly _tag: Tag;
+    }, A, E, R>;
+}
+export declare function DataEffect<const Tag extends string>(tag: Tag): DataEffectClass<Tag>;

package/dist/_internal.js

@@ -0,0 +1,53 @@
+import { Data, Effectable, Equal, Hash, Predicate, Schema, } from 'effect';
+import { structuralRegion } from 'effect/Utils';
+/**
+ * Constructs the same interface as `Schema.Struct`, but with the ability to
+ * wrap it in Data.struct to ensure we can hash the struct.
+ */
+export function DataStruct(fields) {
+    return liftStructIntoDataStruct(Schema.Struct(fields));
+}
+function liftStructIntoDataStruct(struct) {
+    const data = Schema.Data(struct);
+    return Object.assign(data, {
+        make: (...params) => Data.struct(struct.make(...params)),
+        pick: (...params) => liftStructIntoDataStruct(struct.pick(...params)),
+        omit: (...params) => liftStructIntoDataStruct(struct.omit(...params)),
+        fields: struct.fields,
+        records: struct.records,
+        annotations: (...params) => liftStructIntoDataStruct(struct.annotations(...params)),
+    });
+}
+export function LiteralWithDefault() {
+    return (value) => {
+        return Schema.optionalWith(Schema.Literal(value), { default: () => value });
+    };
+}
+class AbstractDataEffect extends Effectable.Class {
+    constructor(fields) {
+        super();
+        Object.assign(this, fields);
+    }
+    [Hash.symbol]() {
+        return Hash.structure(this);
+    }
+    [Equal.symbol](that) {
+        return Predicate.isObject(that) && structuralRegion(() => Equal.equals(this, that));
+    }
+}
+export function DataEffect(tag) {
+    class DataEffect extends AbstractDataEffect {
+        effect;
+        static _tag = tag;
+        _tag = tag;
+        constructor(fields, effect) {
+            super(fields);
+            this.effect = effect;
+        }
+        commit() {
+            return this.effect;
+        }
+    }
+    return DataEffect;
+}
+//# sourceMappingURL=_internal.js.map

package/dist/_internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_internal.js","sourceRoot":"","sources":["../src/_internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EAEJ,UAAU,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,MAAM,GAEP,MAAM,QAAQ,CAAA;AAEf,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc;IAEd,OAAO,wBAAwB,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;AACxD,CAAC;AAED,SAAS,wBAAwB,CAC/B,MAA6B;IAE7B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAEhC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;QACzB,IAAI,EAAE,CAAC,GAAG,MAAsC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QACxF,IAAI,EAAE,CAAwC,GAAG,MAAS,EAAE,EAAE,CAC5D,wBAAwB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAClD,IAAI,EAAE,CAAwC,GAAG,MAAS,EAAE,EAAE,CAC5D,wBAAwB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAClD,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,CAAC,GAAG,MAA6C,EAAE,EAAE,CAChE,wBAAwB,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,CAAC;KAC1D,CAAC,CAAA;AACJ,CAAC;AAOD,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAyC,KAAQ,EAA4B,EAAE;QACpF,OAAO,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAQ,CAAA;IACpF,CAAC,CAAA;AACH,CAAC;AAoBD,MAAe,kBACb,SAAQ,UAAU,CAAC,KAAc;IAGjC,YAAY,MAAS;QACnB,KAAK,EAAE,CAAA;QACP,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC7B,CAAC;IAID,CAAC,IAAI,CAAC,MAAM,CAAC;QACX,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAC7B,CAAC;IAED,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAa;QAC1B,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;IACrF,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAA2B,GAAQ;IAC3D,MAAM,UAKJ,SAAQ,kBAAmC;QAMhC;QALX,MAAM,CAAU,IAAI,GAAG,GAAG,CAAA;QACjB,IAAI,GAAG,GAAG,CAAA;QAEnB,YACE,MAAc,EACL,MAA8B;YAEvC,KAAK,CAAC,MAAM,CAAC,CAAA;YAFJ,WAAM,GAAN,MAAM,CAAwB;QAGzC,CAAC;QAED,MAAM;YACJ,OAAO,IAAI,CAAC,MAAM,CAAA;QACpB,CAAC;;IAGH,OAAO,UAAiB,CAAA;AAC1B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './AsyncData.js';
+export * from './LazyRef.js';
+export * from './Progress.js';
+export * from './TypeId.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './AsyncData.js';
+export * from './LazyRef.js';
+export * from './Progress.js';
+export * from './TypeId.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/package.json

@@ -1,56 +1,39 @@
 {
   "name": "@typed/async-data",
-  "version": "0.11.0",
-  "description": "",
+  "version": "0.13.0",
+  "description": "Async Data for Effect",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "keywords": [
+    "async",
+    "data",
+    "effect",
+    "typescript"
+  ],
+  "author": "Tylor Steinberger <tlsteinberger167@gmail.com>",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tylors/typed.git"
-  },
-  "sideEffects": [],
-  "author": "Typed contributors",
   "dependencies": {
-    "@effect/schema": "^0.68.1",
-    "effect": "^3.3.5",
-    "fast-check": "^3.19.0"
+    "@typed/lazy-ref": "^0.3.2",
+    "effect": "^3.11.9"
+  },
+  "peerDependencies": {
+    "@typed/lazy-ref": "^0.3.2",
+    "effect": "^3.11.9"
   },
-  "exports": {
-    "./package.json": "./package.json",
-    "./AsyncData": {
-      "types": "./dist/dts/AsyncData.d.ts",
-      "import": "./dist/esm/AsyncData.js",
-      "default": "./dist/cjs/AsyncData.js"
-    },
-    "./Progress": {
-      "types": "./dist/dts/Progress.d.ts",
-      "import": "./dist/esm/Progress.js",
-      "default": "./dist/cjs/Progress.js"
-    },
-    "./Schema": {
-      "types": "./dist/dts/Schema.d.ts",
-      "import": "./dist/esm/Schema.js",
-      "default": "./dist/cjs/Schema.js"
-    },
-    "./TypeId": {
-      "types": "./dist/dts/TypeId.d.ts",
-      "import": "./dist/esm/TypeId.js",
-      "default": "./dist/cjs/TypeId.js"
-    }
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@effect/vitest": "^0.16.0",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.4.2",
+    "vitest": "^2.1.8"
   },
-  "typesVersions": {
-    "*": {
-      "AsyncData": [
-        "./dist/dts/AsyncData.d.ts"
-      ],
-      "Progress": [
-        "./dist/dts/Progress.d.ts"
-      ],
-      "Schema": [
-        "./dist/dts/Schema.d.ts"
-      ],
-      "TypeId": [
-        "./dist/dts/TypeId.d.ts"
-      ]
-    }
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "biome lint --write",
+    "test:watch": "vitest --typecheck",
+    "test": "vitest run --typecheck",
+    "typecheck": "tsc --noEmit"
   }
 }

package/readme.md

@@ -0,0 +1,218 @@
+# @typed/async-data
+
+A type-safe, Effect-based library for managing asynchronous data states in TypeScript applications. Built on top of the Effect ecosystem, it provides a powerful and composable way to handle loading, success, failure, and optimistic states of your data.
+
+Key benefits:
+- 🎯 **Type-safe**: Full TypeScript support with strict typing
+- 🔄 **Effect Integration**: Seamless integration with the Effect ecosystem
+- 📊 **Progress Tracking**: Built-in support for loading progress
+- 🎭 **State Management**: Comprehensive state handling for async operations
+- 🔄 **Optimistic Updates**: First-class support for optimistic UI updates
+- 🛡️ **Error Handling**: Type-safe error handling with Effect
+
+## Installation
+
+```bash
+npm install @typed/async-data
+# or
+pnpm add @typed/async-data
+# or
+yarn add @typed/async-data
+```
+
+## Basic Usage
+
+```typescript
+import * as AsyncData from '@typed/async-data'
+import { Effect } from 'effect'
+
+// Create an AsyncData instance
+const noData = AsyncData.noData()
+const loading = AsyncData.loading()
+const success = AsyncData.success(1)
+const failure = AsyncData.failure(Cause.fail('error'))
+const refreshing = AsyncData.refreshing(AsyncData.success(1))
+const optimistic = AsyncData.optimistic(AsyncData.loading(), 1)
+```
+
+## Core Features
+
+### State Types
+
+AsyncData represents data that can be in one of six states:
+
+1. `NoData` - Initial state when no data has been loaded
+2. `Loading` - Data is being loaded for the first time
+3. `Success<A>` - Successfully loaded data of type A
+4. `Failure<E>` - Failed to load data with error of type E
+5. `Refreshing<A, E>` - Reloading data while preserving previous state
+6. `Optimistic<A, E>` - Optimistically updated while waiting for confirmation
+
+### Effect Integration
+
+AsyncData instances are Effect values, allowing seamless integration with Effect's ecosystem:
+
+```typescript
+import { Effect, Cause } from 'effect'
+import * as AsyncData from '@typed/async-data'
+
+const program = Effect.gen(function* (_) {
+  // NoData and Loading are Failures
+  const noData = AsyncData.noData()
+  const noDataExit = yield* Effect.exit(noData)
+  // noDataExit === Exit.fail(noData)
+
+  // Success values are Successes
+  const success = AsyncData.success(1)
+  const value = yield* success
+  // value === 1
+
+  // Refreshing preserves the previous state
+  const refreshing = AsyncData.refreshing(AsyncData.success(1))
+  const refreshValue = yield* refreshing
+  // refreshValue === 1
+
+  // Optimistic updates provide immediate feedback
+  const optimistic = AsyncData.optimistic(AsyncData.fail('not used'), 1)
+  const optValue = yield* optimistic
+  // optValue === 1
+})
+```
+
+### LazyRef Integration
+
+AsyncData can be used with LazyRef for managing state over time:
+
+```typescript
+import { Effect, Schema } from 'effect'
+import * as AsyncData from '@typed/async-data'
+
+// Define a schema-based AsyncData type
+class Example extends AsyncData.AsyncData({
+  success: Schema.Number,
+  failure: Schema.String,
+}) {}
+
+const program = Effect.gen(function* (_) {
+  // Create a lazy reference
+  const example = yield* AsyncData.lazyRef(Example)
+
+  // Run an async operation
+  yield* Effect.forkScoped(
+    AsyncData.runEffect(
+      example,
+      Effect.delay(Effect.succeed(1), 500)
+    )
+  )
+
+  // State transitions automatically
+  const initial = yield* example
+  // initial === Example.noData()
+
+  yield* TestClock.adjust(1)
+  const loading = yield* example
+  // loading === Example.loading()
+
+  yield* TestClock.adjust(500)
+  const final = yield* example
+  // final === Example.success(1)
+})
+```
+
+### Progress Tracking
+
+AsyncData includes built-in support for tracking loading progress:
+
+```typescript
+import * as AsyncData from '@typed/async-data'
+import { Progress } from '@typed/async-data'
+
+// Create loading state with progress
+const progress = Progress.make({ 
+  loaded: 50,
+  total: Option.some(100)
+})
+const loading = AsyncData.loading(progress)
+
+// Update progress
+const updated = AsyncData.updateProgress(loading, 
+  Progress.make({ loaded: 75, total: Option.some(100) })
+)
+```
+
+### Pattern Matching
+
+AsyncData provides comprehensive pattern matching capabilities:
+
+```typescript
+import * as AsyncData from '@typed/async-data'
+
+const result = AsyncData.match(data, {
+  NoData: () => 'No data yet',
+  Loading: (progress) => `Loading... ${progress}`,
+  Success: (value, { isRefreshing, isOptimistic }) => 
+    `Value: ${value} ${isRefreshing ? '(refreshing)' : ''} ${isOptimistic ? '(optimistic)' : ''}`,
+  Failure: (cause, { isRefreshing }) => 
+    `Error: ${cause} ${isRefreshing ? '(refreshing)' : ''}`
+})
+```
+
+## Advanced Usage
+
+### Tagged Services
+
+Create tagged services with AsyncData:
+
+```typescript
+import * as AsyncData from '@typed/async-data'
+import { Effect, Schema } from 'effect'
+
+const UserService = AsyncData.Tag('UserService')<
+  typeof UserService,
+  User,
+  string
+>()
+
+const program = Effect.gen(function* (_) {
+  const users = yield* UserService
+  
+  // Run effects and automatically manage state
+  yield* UserService.run(
+    Effect.succeed({ id: 1, name: 'John' })
+  )
+})
+
+// Provide implementation
+program.pipe(
+  Effect.provide(UserService.Default)
+)
+```
+
+### Type-safe Error Handling
+
+AsyncData ensures type-safe error handling:
+
+```typescript
+import * as AsyncData from '@typed/async-data'
+import { Effect, Cause } from 'effect'
+
+type ApiError = { code: number; message: string }
+
+const result = AsyncData.failure<ApiError>(
+  Cause.fail({ code: 404, message: 'Not found' })
+)
+
+AsyncData.match(result, {
+  Failure: (cause) => {
+    // cause is typed as Cause<ApiError>
+    const errors = Array.from(Cause.failures(cause))
+    // Handle errors
+  },
+  // ... other cases
+})
+```
+
+## License
+
+MIT
+

package/src/AsyncData.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from '@effect/vitest'
+import { Cause, Effect, Exit, Schema, TestClock } from 'effect'
+import * as AsyncData from './index.js'
+
+describe('AsyncData', () => {
+  describe('Effect', () => {
+    it.effect('NoData is a Failure', () =>
+      Effect.gen(function* () {
+        const noData = AsyncData.noData()
+        const exit = yield* Effect.exit(noData)
+
+        expect(exit).toEqual(Exit.fail(noData))
+      }),
+    )
+
+    it.effect('Loading is a Failure', () =>
+      Effect.gen(function* () {
+        const loading = AsyncData.loading()
+        const exit = yield* Effect.exit(loading)
+
+        expect(exit).toEqual(Exit.fail(loading))
+      }),
+    )
+
+    it.effect('Failure is a Failure', () =>
+      Effect.gen(function* () {
+        const cause = Cause.fail('test')
+        const failure = AsyncData.failure(cause)
+        const exit = yield* Effect.exit(failure)
+
+        expect(exit).toEqual(Exit.failCause(cause))
+      }),
+    )
+
+    it.effect('Success is a Success', () =>
+      Effect.gen(function* () {
+        expect(yield* AsyncData.success(1)).toEqual(1)
+      }),
+    )
+
+    it.effect('Refreshing<Success> is a Success', () =>
+      Effect.gen(function* () {
+        expect(yield* AsyncData.refreshing(AsyncData.success(1))).toEqual(1)
+      }),
+    )
+
+    it.effect('Refreshing<Failure> is a Failure', () =>
+      Effect.gen(function* () {
+        const cause = Cause.fail('test')
+        const failure = AsyncData.failure(cause)
+        const exit = yield* Effect.exit(AsyncData.refreshing(failure))
+
+        expect(exit).toEqual(Exit.failCause(cause))
+      }),
+    )
+
+    it.effect('Optimistic is a Success', () =>
+      Effect.gen(function* () {
+        expect(yield* AsyncData.optimistic(AsyncData.fail('not used'), 1)).toEqual(1)
+      }),
+    )
+  })
+
+  describe('Schema + LazyRef', () => {
+    class Example extends AsyncData.AsyncData({
+      success: Schema.Number,
+      failure: Schema.String,
+    }) {}
+
+    it.scoped('keeps state', () =>
+      Effect.gen(function* () {
+        const example = yield* AsyncData.lazyRef(Example)
+
+        // Simulate an async operation
+        yield* Effect.forkScoped(AsyncData.runEffect(example, Effect.delay(Effect.succeed(1), 500)))
+
+        expect(yield* example).toEqual(Example.noData())
+
+        yield* TestClock.adjust(1)
+
+        expect(yield* example).toEqual(Example.loading())
+
+        yield* TestClock.adjust(500)
+
+        expect(yield* example).toEqual(Example.success(1))
+      }),
+    )
+  })
+})