polen 0.11.0-next.13 → 0.11.0-next.15

package/src/lib/services-crud/browser-ro.ts

@@ -0,0 +1,98 @@
+import { Data, Effect, Layer } from 'effect'
+import { CrudService } from './service.js'
+
+/**
+ * Structured error types for browser read-only operations
+ */
+export class FetchError extends Data.TaggedError('FetchError')<{
+  readonly url: string
+  readonly status: number
+  readonly statusText: string
+}> {}
+
+export class NetworkError extends Data.TaggedError('NetworkError')<{
+  readonly relativePath: string
+  readonly cause: unknown
+}> {}
+
+export class UnsupportedOperationError extends Data.TaggedError('UnsupportedOperationError')<{
+  readonly operation: string
+  readonly message: string
+}> {}
+
+/**
+ * Create a read-only CRUD service layer for browser environments.
+ *
+ * This service uses the fetch API to read files from a remote server.
+ * Write, list, and remove operations are not supported and will fail
+ * with descriptive error messages.
+ *
+ * This is ideal for:
+ * - Loading static data from a CDN or static server
+ * - Reading configuration files in browser applications
+ * - Fetching pre-generated data exports
+ *
+ * For write operations in browser environments, implement a custom
+ * service that uses your API endpoints.
+ *
+ * @param baseUrl - Base URL for all fetch operations
+ * @returns Layer providing read-only CrudService backed by HTTP fetch
+ */
+export const browserReadOnly = (baseUrl: string) => {
+  const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/'
+
+  return Layer.succeed(CrudService, {
+    read: (relativePath: string) =>
+      Effect.gen(function*() {
+        const url = new URL(relativePath, normalizedBaseUrl).toString()
+
+        const response = yield* Effect.tryPromise({
+          try: () => fetch(url),
+          catch: (cause) => new NetworkError({ relativePath, cause }),
+        })
+
+        if (!response.ok) {
+          return yield* Effect.fail(
+            new FetchError({
+              url,
+              status: response.status,
+              statusText: response.statusText,
+            }),
+          )
+        }
+
+        return yield* Effect.tryPromise({
+          try: () => response.text(),
+          catch: (cause) => new NetworkError({ relativePath, cause }),
+        })
+      }),
+
+    write: (_relativePath: string, _data: string) =>
+      Effect.fail(
+        new UnsupportedOperationError({
+          operation: 'write',
+          message: 'Write operations not supported by Browser Read-Only service. '
+            + 'Use a server-side CRUD service or implement a custom browser service for your API.',
+        }),
+      ),
+
+    list: (_relativePath: string) =>
+      Effect.fail(
+        new UnsupportedOperationError({
+          operation: 'list',
+          message: 'List operations not supported by Browser Read-Only service. '
+            + 'Browser environments cannot list remote directories. '
+            + 'Consider using a manifest file or selection-based loading.',
+        }),
+      ),
+
+    remove: (_relativePath: string) =>
+      Effect.fail(
+        new UnsupportedOperationError({
+          operation: 'remove',
+          message: 'Remove operations not supported by Browser Read-Only service. '
+            + 'Use a server-side CRUD service or implement a custom browser service for your API.',
+        }),
+      ),
+  })
+}

package/src/lib/services-crud/filesystem.ts

@@ -0,0 +1,63 @@
+import { FileSystem, Path } from '@effect/platform'
+import { NodeFileSystem, NodePath } from '@effect/platform-node'
+import { Effect, Layer } from 'effect'
+import { CrudService } from './service.js'
+
+/**
+ * Create a CRUD service layer that adapts Effect Platform FileSystem service.
+ *
+ * This adapter bridges the gap between the generic CRUD service interface and
+ * the rich FileSystem service from Effect Platform. It handles:
+ * - Auto-creation of parent directories on write
+ * - Path resolution relative to the base path
+ * - Error mapping from PlatformError to generic Error
+ * - Graceful handling of missing files/directories
+ *
+ * @param basePath - Base directory path for all operations
+ * @returns Layer providing CrudService backed by FileSystem
+ */
+export const fromFileSystem = (basePath: string) =>
+  Layer.effect(
+    CrudService,
+    Effect.gen(function*() {
+      const fs = yield* FileSystem.FileSystem
+      const path = yield* Path.Path
+
+      return {
+        read: (relativePath: string) =>
+          fs.readFileString(path.join(basePath, relativePath))
+            .pipe(Effect.mapError(error => new Error(`Failed to read ${relativePath}: ${error}`))),
+
+        write: (relativePath: string, data: string) =>
+          Effect.gen(function*() {
+            const fullPath = path.join(basePath, relativePath)
+            const dir = path.dirname(fullPath)
+            yield* fs.makeDirectory(dir, { recursive: true })
+            yield* fs.writeFileString(fullPath, data)
+          }).pipe(Effect.mapError(error => new Error(`Failed to write ${relativePath}: ${error}`))),
+
+        list: (relativePath: string) =>
+          fs.readDirectory(path.join(basePath, relativePath))
+            .pipe(
+              Effect.catchTag(
+                'SystemError',
+                error => error.reason === 'NotFound' ? Effect.succeed([]) : Effect.fail(error),
+              ),
+              Effect.mapError(error => new Error(`Failed to list ${relativePath}: ${error}`)),
+            ),
+
+        remove: (relativePath: string) =>
+          fs.remove(path.join(basePath, relativePath))
+            .pipe(
+              Effect.catchTag(
+                'SystemError',
+                error => error.reason === 'NotFound' ? Effect.succeed(undefined) : Effect.fail(error),
+              ),
+              Effect.mapError(error => new Error(`Failed to remove ${relativePath}: ${error}`)),
+            ),
+      }
+    }),
+  ).pipe(
+    Layer.provide(NodeFileSystem.layer),
+    Layer.provide(NodePath.layer),
+  )

package/src/lib/services-crud/memory.ts

@@ -0,0 +1,86 @@
+import { Effect, Layer } from 'effect'
+import * as path from 'node:path'
+import { CrudService } from './service.js'
+
+/**
+ * Options for configuring the memory CRUD service.
+ */
+export interface MemoryOptions {
+  /**
+   * Base path for all operations (defaults to '.')
+   */
+  basePath?: string
+
+  /**
+   * Initial files to populate the memory filesystem
+   */
+  initialFiles?: Map<string, string> | Record<string, string>
+}
+
+/**
+ * Create a CRUD service layer backed by in-memory storage.
+ *
+ * This service stores all data in memory using a Map, making it perfect for:
+ * - Unit testing with isolated, predictable state
+ * - Temporary data storage that doesn't need persistence
+ * - Fast operations without disk I/O overhead
+ *
+ * The service maintains proper path semantics and directory structure
+ * simulation while keeping everything in memory.
+ *
+ * @param options - Configuration options
+ * @returns Layer providing CrudService backed by memory storage
+ */
+export const memory = (options?: MemoryOptions) => {
+  const basePath = options?.basePath || '.'
+  const initialFilesInput = options?.initialFiles instanceof Map
+    ? options.initialFiles
+    : new Map(Object.entries(options?.initialFiles || {}))
+
+  // Convert initial files to use full paths and create persistent storage
+  const files = new Map<string, string>()
+  for (const [filename, content] of initialFilesInput) {
+    const fullPath = path.join(basePath, filename)
+    files.set(fullPath, content)
+  }
+
+  return Layer.succeed(CrudService, {
+    read: (relativePath: string) =>
+      Effect.sync(() => {
+        const fullPath = path.join(basePath, relativePath)
+        const content = files.get(fullPath)
+        if (content === undefined) {
+          throw new Error(`File not found: ${relativePath}`)
+        }
+        return content
+      }),
+
+    write: (relativePath: string, data: string) =>
+      Effect.sync(() => {
+        const fullPath = path.join(basePath, relativePath)
+        files.set(fullPath, data)
+      }),
+
+    list: (relativePath: string) =>
+      Effect.sync(() => {
+        const searchPath = path.join(basePath, relativePath)
+        const normalizedSearchPath = searchPath.endsWith('/') ? searchPath : searchPath + '/'
+
+        // Find all files in the directory
+        return Array.from(files.keys())
+          .filter(filePath => {
+            const dir = path.dirname(filePath)
+            const normalizedDir = dir.endsWith('/') ? dir : dir + '/'
+            return normalizedDir === normalizedSearchPath
+              || (searchPath === basePath && dir === searchPath)
+          })
+          .map(filePath => path.basename(filePath))
+      }),
+
+    remove: (relativePath: string) =>
+      Effect.sync(() => {
+        const fullPath = path.join(basePath, relativePath)
+        files.delete(fullPath)
+      }),
+  })
+}

package/src/lib/services-crud/service.ts

@@ -0,0 +1,49 @@
+import { Context, Effect } from 'effect'
+
+/**
+ * Core CRUD service interface for basic file operations.
+ *
+ * This interface provides platform-agnostic CRUD operations for string-based file content.
+ * Implementations can target different platforms (filesystem, memory, HTTP, etc.) while
+ * maintaining the same interface contract.
+ */
+export interface CrudService {
+  /**
+   * Read file contents as a string.
+   *
+   * @param path - Relative path to the file
+   * @returns Effect resolving to file contents as string
+   */
+  readonly read: (path: string) => Effect.Effect<string, Error>
+
+  /**
+   * Write string data to a file.
+   * Implementations should auto-create parent directories as needed.
+   *
+   * @param path - Relative path to the file
+   * @param data - String content to write
+   * @returns Effect resolving when write is complete
+   */
+  readonly write: (path: string, data: string) => Effect.Effect<void, Error>
+
+  /**
+   * List contents of a directory.
+   *
+   * @param path - Relative path to the directory
+   * @returns Effect resolving to array of filenames in the directory
+   */
+  readonly list: (path: string) => Effect.Effect<readonly string[], Error>
+
+  /**
+   * Remove a file or directory.
+   *
+   * @param path - Relative path to the file or directory to remove
+   * @returns Effect resolving when removal is complete
+   */
+  readonly remove: (path: string) => Effect.Effect<void, Error>
+}
+
+/**
+ * Service tag for dependency injection.
+ */
+export const CrudService = Context.GenericTag<CrudService>('@polen/services-crud/CrudService')

package/src/lib/stack-processor/stack-processor.ts

@@ -1,6 +1,29 @@
 import type { Bool, Fn, Prom } from '@wollybeard/kit'
 import { Undefined } from '@wollybeard/kit'
+import { Effect } from 'effect'
 
+/**
+ * Effect-based version that processes functions sequentially until predicate is met
+ */
+export const untilEffect = <A extends readonly unknown[], R, E, Context>(
+  predicate: (value: R) => boolean,
+) =>
+<fns extends readonly ((..._: A) => Effect.Effect<R, E, Context>)[]>(
+  fns: fns,
+) =>
+(...args: A): Effect.Effect<R | undefined, E, Context> =>
+  Effect.gen(function*() {
+    for (const fn of fns) {
+      const result = yield* fn(...args)
+      if (predicate(result)) return result
+    }
+    return undefined
+  })
+
+/**
+ * Legacy Promise-based version for backward compatibility
+ * @deprecated Use untilEffect for better error handling and composition
+ */
 export const until = (
   predicate: Bool.Predicate,
 ) =>
@@ -15,4 +38,13 @@ export const until = (
   }
 }
 
+/**
+ * Effect-based version that processes functions until a defined result is found
+ */
+export const untilDefinedEffect = untilEffect(Undefined.isnt)
+
+/**
+ * Legacy Promise-based version for backward compatibility
+ * @deprecated Use untilDefinedEffect
+ */
 export const untilDefined = until(Undefined.isnt)

package/src/lib/task/$.test.ts

@@ -1,15 +1,16 @@
+import { Effect } from 'effect'
 import * as fc from 'fast-check'
 import { describe, expect, test, vi } from 'vitest'
 import { Task } from './$.js'
 
 describe('create', () => {
-  test('executes async function and captures timing', async () => {
+  test('executes Effect function and captures timing', async () => {
     const double = Task.create(
-      async (x: number) => x * 2,
+      (x: number) => Effect.succeed(x * 2),
       { name: 'double' },
     )
 
-    const report = await double(5)
+    const report = await Effect.runPromise(double(5))
 
     expect(report.task.name).toBe('double')
     expect(report.execution.input).toBe(5)
@@ -19,26 +20,25 @@ describe('create', () => {
 
   test('captures errors', async () => {
     const failing = Task.create(
-      async () => {
-        throw new Error('Failed')
-      },
+      () => Effect.fail(new Error('Failed')),
       { name: 'failing' },
     )
 
-    const report = await failing(null)
+    const report = await Effect.runPromise(failing(null))
 
     expect(report.execution.output).toBeInstanceOf(Error)
-    expect(report.execution.output.message).toBe('Failed')
+    expect((report.execution.output as Error).message).toBe('Failed')
   })
 })
 
 describe('formatReport', () => {
   test('masks sensitive data', async () => {
     const createUser = Task.create(
-      async (data: any) => ({
-        email: data.email,
-        token: 'abc123',
-      }),
+      (data: any) =>
+        Effect.succeed({
+          email: data.email,
+          token: 'abc123',
+        }),
       {
         name: 'create-user',
         mask: {
@@ -48,10 +48,10 @@ describe('formatReport', () => {
       },
     )
 
-    const report = await createUser({
+    const report = await Effect.runPromise(createUser({
       email: 'user@example.com',
       password: 'secret',
-    })
+    }))
 
     // Uses mask from task definition by default
     const formatted = Task.formatReport(report)
@@ -64,10 +64,11 @@ describe('formatReport', () => {
 
   test('debug mode reveals all data', async () => {
     const createUser = Task.create(
-      async (data: any) => ({
-        email: data.email,
-        token: 'abc123',
-      }),
+      (data: any) =>
+        Effect.succeed({
+          email: data.email,
+          token: 'abc123',
+        }),
       {
         name: 'create-user',
         mask: {
@@ -77,10 +78,10 @@ describe('formatReport', () => {
       },
     )
 
-    const report = await createUser({
+    const report = await Effect.runPromise(createUser({
       email: 'user@example.com',
       password: 'secret',
-    })
+    }))
 
     const formatted = Task.formatReport(report, { debug: true })
 
@@ -96,8 +97,8 @@ describe('exitWithReport', () => {
     })
     const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
 
-    const success = Task.create(async () => 'result')
-    const report = await success(null)
+    const success = Task.create(() => Effect.succeed('result'))
+    const report = await Effect.runPromise(success(null))
 
     expect(() => Task.exitWithReport(report)).toThrow('process.exit called')
     expect(mockExit).toHaveBeenCalledWith(0)
@@ -113,10 +114,8 @@ describe('exitWithReport', () => {
     })
     const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
 
-    const failing = Task.create(async () => {
-      throw new Error('Failed')
-    })
-    const report = await failing(null)
+    const failing = Task.create(() => Effect.fail(new Error('Failed')))
+    const report = await Effect.runPromise(failing(null))
 
     expect(() => Task.exitWithReport(report)).toThrow('process.exit called')
     expect(mockExit).toHaveBeenCalledWith(1)
@@ -134,9 +133,11 @@ describe('runAndExit', () => {
     })
     const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
 
-    const double = async (x: number) => x * 2
+    const double = (x: number) => Effect.succeed(x * 2)
 
-    await expect(() => Task.runAndExit(double, 5, { name: 'double' })).rejects.toThrow('process.exit called')
+    await expect(() => Effect.runPromise(Task.runAndExit(double, 5, { name: 'double' }))).rejects.toThrow(
+      'process.exit called',
+    )
 
     expect(mockExit).toHaveBeenCalledWith(0)
     expect(mockLog).toHaveBeenCalled()
@@ -156,11 +157,11 @@ describe('runAndExit', () => {
     })
     const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
 
-    const failing = async () => {
-      throw new Error('Task failed')
-    }
+    const failing = () => Effect.fail(new Error('Task failed'))
 
-    await expect(() => Task.runAndExit(failing, null, { name: 'failing' })).rejects.toThrow('process.exit called')
+    await expect(() => Effect.runPromise(Task.runAndExit(failing, null, { name: 'failing' }))).rejects.toThrow(
+      'process.exit called',
+    )
 
     expect(mockExit).toHaveBeenCalledWith(1)
     expect(mockLog).toHaveBeenCalled()
@@ -177,11 +178,11 @@ describe('property-based tests', () => {
         fc.integer(),
         async (input) => {
           const identity = Task.create(
-            async (x: any) => x,
+            (x: any) => Effect.succeed(x),
             { name: 'identity' },
           )
 
-          const report = await identity(input)
+          const report = await Effect.runPromise(identity(input))
 
           expect(report.execution.timings.duration).toBeGreaterThanOrEqual(0)
           expect(report.execution.output).toBe(input)
@@ -195,8 +196,8 @@ describe('property-based tests', () => {
       fc.asyncProperty(
         fc.anything(),
         async (input) => {
-          const noop = Task.create(async (_: any) => null)
-          const report = await noop(input)
+          const noop = Task.create((_: any) => Effect.succeed(null))
+          const report = await Effect.runPromise(noop(input))
 
           const { start, end, duration } = report.execution.timings
 

package/src/lib/task/report.ts

@@ -19,13 +19,13 @@ export interface FormatOptions<$Input, $Output> {
   /**
    * Force masks to reveal all data
    */
-  debug?: boolean
+  debug?: boolean | undefined
   /**
    * A mask to apply to the input (if any) and successful return (if any).
    *
    * @default Uses the mask bundled with the task, if any.
    */
-  mask?: MaskOptions<$Input, $Output>
+  mask?: MaskOptions<$Input, $Output> | undefined
 }
 
 export const formatReport = <$Input, $Output>(