samva 0.0.1 → 0.2.0

package/dist/effect/retry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Default-on retry for the Effect SDK.
+ *
+ * Every retry-safe operation — reads and idempotency-keyed sends — retries out
+ * of the box: transient failures back off with jittered exponential delay, and
+ * `429 RateLimitedError` honors the server's `retryAfterSeconds` hint (capped).
+ * Eligibility is decided by the {@link isRetryable} category predicate; the set
+ * of retry-safe operations is decided by the module adapter (GET/HEAD reads and keyed
+ * sends), so keyless mutating operations are never auto-retried.
+ *
+ * The policy is read from context via {@link Service} using
+ * `Effect.serviceOption`, so the default applies when the service is absent and
+ * no operation gains a requirement. Install {@link layerDisabled} to turn
+ * retries off, or {@link layer} for a custom schedule/options.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import * as Retry from "samva/effect/retry";
+ *
+ * // Disable auto-retry for a program:
+ * program.pipe(Effect.provide(Retry.layerDisabled));
+ * ```
+ */
+import { Context, Effect, Layer } from "effect";
+/**
+ * A retry policy: the transform applied to each retry-safe operation. Modeled as
+ * a function so policies can wrap the effect arbitrarily (retry options, custom
+ * schedules, or no-op passthrough).
+ */
+export interface Interface {
+    readonly retry: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const Service_base: Context.ServiceClass<Service, "samva/Retry", Interface>;
+/**
+ * Context service carrying the SDK's retry policy. Absent → {@link defaultPolicy}
+ * (read through `Effect.serviceOption`, so no operation gains a requirement).
+ */
+export declare class Service extends Service_base {
+}
+export declare const defaultPolicy: Interface;
+export declare const disabledPolicy: Interface;
+export declare const fromOptions: (options: Effect.Retry.Options<unknown>) => Interface;
+export declare const layerDefault: Layer.Layer<Service>;
+export declare const layerDisabled: Layer.Layer<Service>;
+export declare const layer: (options: Effect.Retry.Options<unknown>) => Layer.Layer<Service>;
+/**
+ * Apply the ambient {@link Service} policy to a retry-safe operation. Reads
+ * the policy optionally (default when absent) and keeps the effect's `R`.
+ */
+export declare const withRetry: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Generate a v4-shaped idempotency key through Effect's `Random` service —
+ * deterministic under a seeded/`TestClock` runtime and platform-neutral (no Web
+ * Crypto or bare `Math.random` at the call site). Facade sends evaluate this
+ * once per logical call so the key is stable across auto-retries within the call
+ * and distinct across calls.
+ */
+export declare const generateIdempotencyKey: Effect.Effect<string>;
+export {};

package/dist/effect/retry.js

@@ -0,0 +1,112 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.js";
+import { h as isRetryable } from "../categories-CsUa8ojo.js";
+import { Context, Duration, Effect, Layer, Option, Random, Schedule } from "effect";
+import * as Predicate$1 from "effect/Predicate";
+//#region src/effect/retry.ts
+/**
+* Default-on retry for the Effect SDK.
+*
+* Every retry-safe operation — reads and idempotency-keyed sends — retries out
+* of the box: transient failures back off with jittered exponential delay, and
+* `429 RateLimitedError` honors the server's `retryAfterSeconds` hint (capped).
+* Eligibility is decided by the {@link isRetryable} category predicate; the set
+* of retry-safe operations is decided by the module adapter (GET/HEAD reads and keyed
+* sends), so keyless mutating operations are never auto-retried.
+*
+* The policy is read from context via {@link Service} using
+* `Effect.serviceOption`, so the default applies when the service is absent and
+* no operation gains a requirement. Install {@link layerDisabled} to turn
+* retries off, or {@link layer} for a custom schedule/options.
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import * as Retry from "samva/effect/retry";
+*
+* // Disable auto-retry for a program:
+* program.pipe(Effect.provide(Retry.layerDisabled));
+* ```
+*/
+var retry_exports = /* @__PURE__ */ __exportAll({
+	Service: () => Service,
+	defaultPolicy: () => defaultPolicy,
+	disabledPolicy: () => disabledPolicy,
+	fromOptions: () => fromOptions,
+	generateIdempotencyKey: () => generateIdempotencyKey,
+	layer: () => layer,
+	layerDefault: () => layerDefault,
+	layerDisabled: () => layerDisabled,
+	withRetry: () => withRetry
+});
+/** Retries beyond the initial attempt — total attempts = 1 + `MAX_RETRIES`. */
+const MAX_RETRIES = 3;
+/** First backoff delay; each subsequent attempt multiplies by `BACKOFF_FACTOR`. */
+const BASE_DELAY = Duration.millis(200);
+const BACKOFF_FACTOR = 2;
+/** Ceiling on how long we honor a server `retryAfterSeconds` hint. */
+const MAX_SERVER_HINT = Duration.seconds(60);
+/**
+* Server-provided delay for a `429`: the `retryAfterSeconds` field the api emits
+* on `RateLimitedError`, capped at {@link MAX_SERVER_HINT}. Returns `undefined`
+* for any other error so the jittered backoff delay stands.
+*/
+const serverHintDelay = (error) => {
+	if (!Predicate$1.isTagged(error, "RateLimitedError")) return void 0;
+	const seconds = error.retryAfterSeconds;
+	if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0) return void 0;
+	return Duration.min(Duration.seconds(seconds), MAX_SERVER_HINT);
+};
+/** Jittered exponential backoff for the transient-failure path. */
+const jitteredBackoff = Schedule.jittered(Schedule.exponential(BASE_DELAY, BACKOFF_FACTOR));
+/**
+* Retry a retry-safe effect under the default policy: transient/throttled
+* failures ({@link isRetryable}), bounded to {@link MAX_RETRIES}, delayed by
+* jittered exponential backoff — except a `429` whose `retryAfterSeconds` hint
+* overrides the computed delay (exactly, un-jittered, capped). The schedule
+* reads the just-failed error from its step metadata (`input`).
+*/
+const defaultSchedule = Schedule.modifyDelay(jitteredBackoff, ({ duration, input }) => Effect.succeed(serverHintDelay(input) ?? duration));
+const defaultRetry = (effect) => Effect.retry(effect, {
+	while: isRetryable,
+	times: MAX_RETRIES,
+	schedule: defaultSchedule
+});
+/**
+* Context service carrying the SDK's retry policy. Absent → {@link defaultPolicy}
+* (read through `Effect.serviceOption`, so no operation gains a requirement).
+*/
+var Service = class extends Context.Service()("samva/Retry") {};
+const defaultPolicy = { retry: defaultRetry };
+const disabledPolicy = { retry: (effect) => effect };
+const fromOptions = (options) => ({ retry: (effect) => Effect.retry(effect, options) });
+const layerDefault = Layer.succeed(Service, defaultPolicy);
+const layerDisabled = Layer.succeed(Service, disabledPolicy);
+const layer = (options) => Layer.succeed(Service, fromOptions(options));
+/**
+* Apply the ambient {@link Service} policy to a retry-safe operation. Reads
+* the policy optionally (default when absent) and keeps the effect's `R`.
+*/
+const withRetry = (effect) => Effect.serviceOption(Service).pipe(Effect.flatMap((policyOption) => Option.getOrElse(policyOption, () => defaultPolicy).retry(effect)));
+const HEX = "0123456789abcdef";
+/**
+* Generate a v4-shaped idempotency key through Effect's `Random` service —
+* deterministic under a seeded/`TestClock` runtime and platform-neutral (no Web
+* Crypto or bare `Math.random` at the call site). Facade sends evaluate this
+* once per logical call so the key is stable across auto-retries within the call
+* and distinct across calls.
+*/
+const generateIdempotencyKey = Effect.gen(function* () {
+	const chars = [];
+	for (let index = 0; index < 32; index += 1) {
+		let nibble = yield* Random.nextIntBetween(0, 15);
+		if (index === 12) nibble = 4;
+		else if (index === 16) nibble = nibble & 3 | 8;
+		chars.push(HEX[nibble]);
+	}
+	const hex = chars.join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+});
+//#endregion
+export { Service, defaultPolicy, disabledPolicy, fromOptions, generateIdempotencyKey, layer, layerDefault, layerDisabled, retry_exports as t, withRetry };
+
+//# sourceMappingURL=retry.js.map

package/dist/effect/runtime.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** Decode wire secrets to redacted values and require redacted values when encoding. */
+export declare const Sensitive: <A, E, RD, RE>(schema: Schema.Codec<A, E, RD, RE>) => Schema.RedactedFromValue<Schema.Codec<A, E, RD, RE>>;
+export declare const SensitiveString: Schema.RedactedFromValue<Schema.Codec<string, string, never, never>>;
+export type SensitiveString = typeof SensitiveString.Type;
+export declare const AbsoluteInstant: Schema.decodeTo<Schema.Date, Schema.String, never, never>;
+export type AbsoluteInstant = typeof AbsoluteInstant.Type;