@tuturuuu/utils 0.8.0 → 0.10.0

package/src/effect.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it } from 'vitest';
+import {
+  Effect,
+  forEachConcurrently,
+  fromDataError,
+  fromPromise,
+  runEffectAsResult,
+  serializeTuturuuuEffectError,
+  TuturuuuEffectError,
+  toTuturuuuEffectError,
+  withTuturuuuRetry,
+  withTuturuuuTimeout,
+} from './effect';
+
+describe('@tuturuuu/utils/effect', () => {
+  it('creates tagged Tuturuuu errors with metadata', () => {
+    const error = new TuturuuuEffectError({
+      code: 'TEST_ERROR',
+      message: 'Test failed',
+      status: 418,
+      context: { feature: 'effect' },
+    });
+
+    expect(error._tag).toBe('TuturuuuEffectError');
+    expect(error.message).toBe('Test failed');
+    expect(serializeTuturuuuEffectError(error)).toEqual({
+      _tag: 'TuturuuuEffectError',
+      code: 'TEST_ERROR',
+      message: 'Test failed',
+      status: 418,
+      context: { feature: 'effect' },
+    });
+  });
+
+  it('normalizes unknown errors with fallback metadata', () => {
+    const error = toTuturuuuEffectError(new Error('Boom'), {
+      code: 'FALLBACK',
+      message: 'Fallback message',
+      status: 500,
+    });
+
+    expect(error).toBeInstanceOf(TuturuuuEffectError);
+    expect(error.code).toBe('FALLBACK');
+    expect(error.message).toBe('Boom');
+    expect(error.status).toBe(500);
+  });
+
+  it('converts data/error style operations into successful effects', async () => {
+    const result = await Effect.runPromise(
+      fromDataError(
+        () => Promise.resolve({ data: { id: 'row-1' }, error: null }),
+        {
+          code: 'DATA_ERROR',
+          message: 'Data read failed',
+        }
+      )
+    );
+
+    expect(result).toEqual({ id: 'row-1' });
+  });
+
+  it('converts data/error style failures into typed errors', async () => {
+    const result = await runEffectAsResult(
+      fromDataError(
+        () =>
+          Promise.resolve({
+            data: null,
+            error: {
+              code: 'PGRST116',
+              message: 'No row found',
+              details: 'Expected one row',
+            },
+          }),
+        {
+          code: 'DATA_ERROR',
+          message: 'Data read failed',
+        }
+      )
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'PGRST116',
+        message: 'No row found',
+        context: { details: 'Expected one row' },
+      },
+    });
+  });
+
+  it('converts rejected promises into typed errors', async () => {
+    const result = await runEffectAsResult(
+      fromPromise(() => Promise.reject(new Error('Network failed')), {
+        code: 'NETWORK_FAILED',
+        message: 'Request failed',
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatchObject({
+        _tag: 'TuturuuuEffectError',
+        code: 'NETWORK_FAILED',
+        message: 'Network failed',
+      });
+    }
+  });
+
+  it('returns success and failure result shapes', async () => {
+    await expect(runEffectAsResult(Effect.succeed('ok'))).resolves.toEqual({
+      ok: true,
+      data: 'ok',
+    });
+
+    await expect(
+      runEffectAsResult(
+        Effect.fail(
+          new TuturuuuEffectError({
+            code: 'EXPECTED_FAILURE',
+            message: 'Expected failure',
+          })
+        )
+      )
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'EXPECTED_FAILURE',
+        message: 'Expected failure',
+      },
+    });
+  });
+
+  it('retries expected failures with a typed retry predicate', async () => {
+    let attempts = 0;
+    const program = Effect.flatMap(
+      Effect.sync(() => {
+        attempts += 1;
+        return attempts;
+      }),
+      (attempt) =>
+        attempt < 3
+          ? Effect.fail(
+              new TuturuuuEffectError({
+                code: 'TRANSIENT_FAILURE',
+                message: 'Try again',
+              })
+            )
+          : Effect.succeed('ready')
+    );
+
+    await expect(
+      Effect.runPromise(
+        withTuturuuuRetry(program, {
+          times: 2,
+          while: (error) => error.code === 'TRANSIENT_FAILURE',
+        })
+      )
+    ).resolves.toBe('ready');
+    expect(attempts).toBe(3);
+  });
+
+  it('does not retry when the retry predicate rejects the error', async () => {
+    let attempts = 0;
+
+    const result = await runEffectAsResult(
+      withTuturuuuRetry(
+        Effect.flatMap(
+          Effect.sync(() => {
+            attempts += 1;
+          }),
+          () =>
+            Effect.fail(
+              new TuturuuuEffectError({
+                code: 'PERMANENT_FAILURE',
+                message: 'Do not retry',
+              })
+            )
+        ),
+        {
+          times: 3,
+          while: (error) => error.code === 'TRANSIENT_FAILURE',
+        }
+      )
+    );
+
+    expect(attempts).toBe(1);
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'PERMANENT_FAILURE',
+        message: 'Do not retry',
+      },
+    });
+  });
+
+  it('converts timeouts into Tuturuuu effect errors', async () => {
+    const result = await runEffectAsResult(
+      withTuturuuuTimeout(Effect.never, {
+        code: 'TIMED_OUT',
+        duration: 0,
+        message: 'Operation timed out',
+        context: { operation: 'test' },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        _tag: 'TuturuuuEffectError',
+        code: 'TIMED_OUT',
+        message: 'Operation timed out',
+        context: { operation: 'test' },
+      },
+    });
+  });
+
+  it('runs effectful collections with bounded concurrency', async () => {
+    let active = 0;
+    let maxActive = 0;
+
+    const result = await Effect.runPromise(
+      forEachConcurrently(
+        [1, 2, 3, 4],
+        (item) =>
+          Effect.promise(
+            () =>
+              new Promise<number>((resolve) => {
+                active += 1;
+                maxActive = Math.max(maxActive, active);
+
+                setTimeout(() => {
+                  active -= 1;
+                  resolve(item * 2);
+                }, 5);
+              })
+          ),
+        { concurrency: 2 }
+      )
+    );
+
+    expect(result).toEqual([2, 4, 6, 8]);
+    expect(maxActive).toBeLessThanOrEqual(2);
+  });
+});

package/src/effect.ts

@@ -0,0 +1,259 @@
+import {
+  Cause,
+  Context,
+  Data,
+  Duration,
+  Effect,
+  Either,
+  Exit,
+  Layer,
+  Option,
+  Schedule,
+} from 'effect';
+
+export {
+  Cause,
+  Context,
+  Data,
+  Duration,
+  Effect,
+  Either,
+  Layer,
+  Option,
+  Schedule,
+};
+
+export type TuturuuuEffectErrorContext = Record<string, unknown>;
+
+export interface TuturuuuEffectErrorOptions {
+  readonly code: string;
+  readonly message: string;
+  readonly status?: number;
+  readonly cause?: unknown;
+  readonly context?: TuturuuuEffectErrorContext;
+}
+
+export class TuturuuuEffectError extends Data.TaggedError(
+  'TuturuuuEffectError'
+)<TuturuuuEffectErrorOptions> {}
+
+export interface SerializedTuturuuuEffectError {
+  readonly _tag: 'TuturuuuEffectError';
+  readonly code: string;
+  readonly message: string;
+  readonly status?: number;
+  readonly context?: TuturuuuEffectErrorContext;
+  readonly cause?: {
+    readonly name?: string;
+    readonly message: string;
+  };
+}
+
+export type TuturuuuEffectResult<T> =
+  | {
+      readonly ok: true;
+      readonly data: T;
+    }
+  | {
+      readonly ok: false;
+      readonly error: SerializedTuturuuuEffectError;
+    };
+
+export type DataErrorResult<TData, TError = unknown> = {
+  readonly data: TData;
+  readonly error: TError | null;
+};
+
+export interface TuturuuuEffectRetryOptions<E = unknown> {
+  readonly times?: number;
+  readonly delay?: Duration.DurationInput;
+  readonly while?: (error: E) => boolean;
+}
+
+export interface TuturuuuEffectTimeoutOptions
+  extends TuturuuuEffectErrorOptions {
+  readonly duration: Duration.DurationInput;
+}
+
+export interface TuturuuuEffectConcurrencyOptions {
+  readonly concurrency?: number | 'unbounded';
+}
+
+export const DEFAULT_TUTURUUU_EFFECT_CONCURRENCY = 4;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function readStringProperty(
+  source: Record<string, unknown> | undefined,
+  key: string
+) {
+  const value = source?.[key];
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function readNumberProperty(
+  source: Record<string, unknown> | undefined,
+  key: string
+) {
+  const value = source?.[key];
+  return typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function buildContext(
+  source: Record<string, unknown> | undefined,
+  fallbackContext: TuturuuuEffectErrorContext | undefined
+) {
+  const context: TuturuuuEffectErrorContext = { ...(fallbackContext ?? {}) };
+  const details = readStringProperty(source, 'details');
+  const hint = readStringProperty(source, 'hint');
+
+  if (details) context.details = details;
+  if (hint) context.hint = hint;
+
+  return Object.keys(context).length > 0 ? context : undefined;
+}
+
+export function toTuturuuuEffectError(
+  error: unknown,
+  fallback: TuturuuuEffectErrorOptions
+) {
+  if (error instanceof TuturuuuEffectError) {
+    return error;
+  }
+
+  const source = isRecord(error) ? error : undefined;
+  const message =
+    error instanceof Error && error.message
+      ? error.message
+      : readStringProperty(source, 'message') || fallback.message;
+
+  return new TuturuuuEffectError({
+    code: readStringProperty(source, 'code') || fallback.code,
+    message,
+    status: readNumberProperty(source, 'status') ?? fallback.status,
+    cause: error,
+    context: buildContext(source, fallback.context),
+  });
+}
+
+export function serializeTuturuuuEffectError(
+  error: TuturuuuEffectError
+): SerializedTuturuuuEffectError {
+  return {
+    _tag: error._tag,
+    code: error.code,
+    message: error.message,
+    ...(error.status !== undefined ? { status: error.status } : {}),
+    ...(error.context ? { context: error.context } : {}),
+    ...(error.cause instanceof Error
+      ? {
+          cause: {
+            name: error.cause.name,
+            message: error.cause.message,
+          },
+        }
+      : {}),
+  };
+}
+
+export function fromPromise<T>(
+  evaluate: (signal: AbortSignal) => PromiseLike<T>,
+  fallback: TuturuuuEffectErrorOptions
+): Effect.Effect<T, TuturuuuEffectError> {
+  return Effect.tryPromise({
+    try: evaluate,
+    catch: (error) => toTuturuuuEffectError(error, fallback),
+  });
+}
+
+export function fromDataError<TData, TError = unknown>(
+  operation: (
+    signal: AbortSignal
+  ) => PromiseLike<DataErrorResult<TData, TError>>,
+  fallback: TuturuuuEffectErrorOptions
+): Effect.Effect<TData, TuturuuuEffectError> {
+  return Effect.flatMap(fromPromise(operation, fallback), (result) =>
+    result.error
+      ? Effect.fail(toTuturuuuEffectError(result.error, fallback))
+      : Effect.succeed(result.data)
+  );
+}
+
+export function withTuturuuuRetry<A, E, R>(
+  program: Effect.Effect<A, E, R>,
+  options: TuturuuuEffectRetryOptions<E> = {}
+): Effect.Effect<A, E, R> {
+  const times = Math.max(0, options.times ?? 2);
+
+  if (times === 0) {
+    return program;
+  }
+
+  return program.pipe(
+    Effect.retry({
+      ...(options.delay ? { schedule: Schedule.spaced(options.delay) } : {}),
+      times,
+      ...(options.while ? { while: options.while } : {}),
+    })
+  );
+}
+
+export function withTuturuuuTimeout<A, E, R>(
+  program: Effect.Effect<A, E, R>,
+  options: TuturuuuEffectTimeoutOptions
+): Effect.Effect<A, E | TuturuuuEffectError, R> {
+  return program.pipe(
+    Effect.timeoutFail({
+      duration: options.duration,
+      onTimeout: () =>
+        new TuturuuuEffectError({
+          code: options.code,
+          message: options.message,
+          status: options.status,
+          cause: options.cause,
+          context: options.context,
+        }),
+    })
+  );
+}
+
+export function forEachConcurrently<A, B, E, R>(
+  items: Iterable<A>,
+  evaluate: (item: A, index: number) => Effect.Effect<B, E, R>,
+  options: TuturuuuEffectConcurrencyOptions = {}
+): Effect.Effect<readonly B[], E, R> {
+  return Effect.forEach(items, evaluate, {
+    concurrency: options.concurrency ?? DEFAULT_TUTURUUU_EFFECT_CONCURRENCY,
+  });
+}
+
+export async function runEffectAsResult<T>(
+  program: Effect.Effect<T, TuturuuuEffectError, never>
+): Promise<TuturuuuEffectResult<T>> {
+  const exit = await Effect.runPromiseExit(program);
+
+  if (Exit.isSuccess(exit)) {
+    return {
+      ok: true,
+      data: exit.value,
+    };
+  }
+
+  const failure = Cause.failureOption(exit.cause);
+  const error = Option.isSome(failure)
+    ? failure.value
+    : new TuturuuuEffectError({
+        code: 'EFFECT_DEFECT',
+        message: Cause.pretty(exit.cause),
+        cause: exit.cause,
+      });
+
+  return {
+    ok: false,
+    error: serializeTuturuuuEffectError(error),
+  };
+}

package/src/internal-domains.ts

@@ -60,6 +60,10 @@ export const PRODUCTION_INTERNAL_APP_DOMAINS = [
     name: 'finance',
     url: 'https://finance.tuturuuu.com',
   },
+  {
+    name: 'infra',
+    url: 'https://infra.tuturuuu.com',
+  },
   {
     name: 'inventory',
     url: 'https://inventory.tuturuuu.com',
@@ -68,6 +72,10 @@ export const PRODUCTION_INTERNAL_APP_DOMAINS = [
     name: 'storefront',
     url: 'https://storefront.tuturuuu.com',
   },
+  {
+    name: 'tanstack-web',
+    url: 'https://tanstack.tuturuuu.com',
+  },
   {
     name: 'track',
     url: 'https://track.tuturuuu.com',
@@ -143,6 +151,10 @@ export const PORTLESS_INTERNAL_APP_DOMAINS = [
     name: 'finance',
     url: getTuturuuuPortlessAppOrigin('finance'),
   },
+  {
+    name: 'infra',
+    url: getTuturuuuPortlessAppOrigin('infra'),
+  },
   {
     name: 'inventory',
     url: getTuturuuuPortlessAppOrigin('inventory'),
@@ -151,6 +163,10 @@ export const PORTLESS_INTERNAL_APP_DOMAINS = [
     name: 'storefront',
     url: getTuturuuuPortlessAppOrigin('storefront'),
   },
+  {
+    name: 'tanstack-web',
+    url: getTuturuuuPortlessAppOrigin('tanstack-web'),
+  },
   {
     name: 'track',
     url: getTuturuuuPortlessAppOrigin('track'),
@@ -226,6 +242,10 @@ export const LOCALHOST_INTERNAL_APP_DOMAINS = [
     name: 'finance',
     url: 'http://localhost:7808',
   },
+  {
+    name: 'infra',
+    url: 'http://localhost:7823',
+  },
   {
     name: 'inventory',
     url: 'http://localhost:7815',
@@ -234,6 +254,10 @@ export const LOCALHOST_INTERNAL_APP_DOMAINS = [
     name: 'storefront',
     url: 'http://localhost:7822',
   },
+  {
+    name: 'tanstack-web',
+    url: 'http://localhost:7824',
+  },
   {
     name: 'track',
     url: 'http://localhost:7810',

package/src/platform-release.test.ts

@@ -7,7 +7,7 @@ import {
 
 describe('platform release metadata', () => {
   it('uses the centralized shared browser app version', () => {
-    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.12.0'); // x-release-please-version
+    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.14.0'); // x-release-please-version
   });
 
   it('normalizes generated metadata and derives a short hash', () => {

package/src/platform-release.ts

@@ -1,6 +1,6 @@
 import { PLATFORM_BUILD_METADATA } from './generated/platform-build-metadata';
 
-export const TUTURUUU_PLATFORM_VERSION = '0.12.0'; // x-release-please-version
+export const TUTURUUU_PLATFORM_VERSION = '0.14.0'; // x-release-please-version
 
 export type PlatformBuildMetadataInput = {
   builtAt?: string | null;

package/src/portless.ts

@@ -15,6 +15,7 @@ export const TUTURUUU_PORTLESS_APP_ORIGINS = {
   finance: `https://finance.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   hive: `https://hive.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   'hive-realtime': `https://realtime.hive.${TUTURUUU_PORTLESS_ROOT_HOST}`,
+  infra: `https://infra.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   inventory: `https://inventory.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   learn: `https://learn.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   mail: `https://mail.${TUTURUUU_PORTLESS_ROOT_HOST}`,
@@ -27,6 +28,7 @@ export const TUTURUUU_PORTLESS_APP_ORIGINS = {
   rewise: `https://rewise.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   shortener: `https://shortener.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   storefront: `https://storefront.${TUTURUUU_PORTLESS_ROOT_HOST}`,
+  'tanstack-web': `https://tanstack.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   tasks: `https://tasks.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   teach: `https://teach.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   track: `https://track.${TUTURUUU_PORTLESS_ROOT_HOST}`,