Buckets API

Generated public TypeScript reference for @relkit/buckets.

Common APIs

• defineBucket

For configuration and examples, read define, organization, uploads.

For a complete workflow, follow upload product images.

Public imports

• @relkit/buckets — 48 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

bucket-validation-error.ts

BucketValidationError (class)

Invalid bucket authoring input, retained in the Effect error channel.

Example

Effect.catchTag(defineBucketEffect(input), "BucketValidationError", () => Effect.void);

Signature

declare class BucketValidationError

Source

client-abort.ts

runAbortableEffect

Runs provider work with a scoped abort listener and deadline.

Example

Effect.runPromise(runAbortableEffect(new AbortController().signal, undefined, Effect.succeed(1)));

Signature

declare const runAbortableEffect: <A, E, R>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | BucketOperationCancelledError | BucketOperationTimeoutError, R>;

Source

client-effects.ts

createBucketReadUrlEffect

Creates a signed read URL when supported.

Example

Effect.provide(createBucketReadUrlEffect("a"), layer);

Signature

declare const createBucketReadUrlEffect: (
  key: string,
) => Effect.Effect<
  string,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

createBucketWriteUrlEffect

Creates a signed write URL when supported.

Example

Effect.provide(createBucketWriteUrlEffect("a"), layer);

Signature

declare const createBucketWriteUrlEffect: (
  key: string,
) => Effect.Effect<
  string,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

deleteBucketEffect

Deletes one key.

Example

Effect.provide(deleteBucketEffect("a"), layer);

Signature

declare const deleteBucketEffect: (
  key: string,
) => Effect.Effect<
  void,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

existsBucketEffect

Checks whether one key exists.

Example

Effect.provide(existsBucketEffect("a"), layer);

Signature

declare const existsBucketEffect: (
  key: string,
) => Effect.Effect<
  boolean,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

getBucketEffect

Reads bytes for one key.

Example

Effect.provide(getBucketEffect("a"), layer);

Signature

declare const getBucketEffect: (
  key: string,
) => Effect.Effect<
  Uint8Array<ArrayBufferLike> | undefined,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

headBucketEffect

Reads metadata for one key.

Example

Effect.provide(headBucketEffect("a"), layer);

Signature

declare const headBucketEffect: (
  key: string,
) => Effect.Effect<
  BucketObjectMetadata | undefined,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

listBucketEffect

Lists keys under an optional prefix.

Example

Effect.provide(listBucketEffect("images/"), layer);

Signature

declare const listBucketEffect: (
  prefix?: string | undefined,
) => Effect.Effect<
  ReadonlyArray<string>,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

putBucketEffect

Stores bytes under a portable key.

Example

Effect.provide(putBucketEffect("a", new Uint8Array()), layer);

Signature

declare const putBucketEffect: (
  key: string,
  bytes: Uint8Array<ArrayBufferLike>,
  options?: BucketPutOptions | undefined,
) => Effect.Effect<
  void,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

client-errors.ts

BucketCapabilityError (class)

An operation requires a capability absent from the provider.

Example

new BucketCapabilityError("signedReadUrl", "createReadUrl");

Signature

declare class BucketCapabilityError {
  constructor(capability: BucketCapability, operation: BucketOperation);
}

Source

code (property)

Signature

readonly code: "RELKIT_BUCKET_CAPABILITY_UNSUPPORTED"

Source

BucketDependencyError (class)

A function used a bucket without declaring its dependency.

Example

new BucketDependencyError("assets");

Signature

declare class BucketDependencyError {
  constructor(bucketId: string);
}

Source

code (property)

Signature

readonly code: "RELKIT_BUCKET_DEPENDENCY_UNDECLARED"

Source

BucketOperationCancelledError (class)

The caller’s signal cancelled a bucket operation.

Example

new BucketOperationCancelledError();

Signature

declare class BucketOperationCancelledError {
  constructor();
}

Source

code (property)

Signature

readonly code: "ABORT_ERR"

Source

BucketOperationTimeoutError (class)

A deadline expired before a bucket operation completed.

Example

new BucketOperationTimeoutError();

Signature

declare class BucketOperationTimeoutError {
  constructor();
}

Source

code (property)

Signature

readonly code: "ETIMEDOUT"

Source

BucketProviderError (class)

A provider omitted a requested operation.

Example

new BucketProviderError("get");

Signature

declare class BucketProviderError {
  constructor(operation: BucketOperation);
}

Source

code (property)

Signature

readonly code: "RELKIT_BUCKET_PROVIDER_UNAVAILABLE"

Source

BucketProviderFailureError (class)

Provider rejection or malformed provider output.

Example

new BucketProviderFailureError({ operation: "get", cause: "offline" });

Signature

declare class BucketProviderFailureError

Source

client-key.ts

assertKey

Synchronous compatibility key assertion.

Throws

TypeError when invalid.

Example

assertKey("images/logo.png");

Signature

declare const assertKey: (value: string) => void;

Source

assertPrefix

Synchronous compatibility prefix assertion.

Throws

TypeError when invalid.

Example

assertPrefix("images/");

Signature

declare const assertPrefix: (value: string) => void;

Source

validateKeyEffect

Validate a portable object key in Effect.

Example

Effect.runSync(validateKeyEffect("images/logo.png"));

Signature

declare const validateKeyEffect: (
  value: string,
) => Effect.Effect<void, BucketValidationError, never>;

Source

validatePrefixEffect

Validate a portable prefix in Effect.

Example

Effect.runSync(validatePrefixEffect("images/"));

Signature

declare const validatePrefixEffect: (
  value: string,
) => Effect.Effect<void, BucketValidationError, never>;

Source

validateTextIdEffect

Validate nonempty identifying text in Effect.

Example

Effect.runSync(validateTextIdEffect("assets", "bucketId"));

Signature

declare const validateTextIdEffect: (
  value: string,
  name: string,
) => Effect.Effect<void, BucketValidationError, never>;

Source

client-observability.ts

BucketTelemetry (class)

Injectable observer for bucket Effect operations.

Example

Effect.provide(getBucketEffect("a"), BucketTelemetryLive);

Signature

declare class BucketTelemetry

Source

BucketTelemetryLive

Live bucket spans and bounded Effect metrics.

Example

Effect.provide(getBucketEffect("a"), BucketTelemetryLive);

Signature

declare const BucketTelemetryLive: Layer.Layer<BucketTelemetry, never, never>;

Source

observeBucket

Measures an operation using fixed operation labels.

Example

observeBucket("get", Effect.succeed(undefined));

Signature

declare const observeBucket: <A, E, R>(
  operation:
    | BucketOperation
    | "define"
    | "isDescriptor"
    | "assertDescriptor"
    | "createClient"
    | "asProvider",
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;

Source

client-observability.types.ts

BucketTelemetryService (interface)

Substitutable observation boundary for bucket operations.

Example

const telemetry: BucketTelemetryService = { observe: (_operation, effect) => effect };

Signature

export interface BucketTelemetryService {
  /** Wrap an operation with spans and metrics.
   * @param operation - Fixed operation name.
   * @param effect - Effect to observe.
   * @returns Effect with the same success and error channels.
   * @example telemetry.observe("get", Effect.succeed(undefined));
   */
  readonly observe: <A, E, R>(
    operation:
      | BucketOperation
      | "define"
      | "isDescriptor"
      | "assertDescriptor"
      | "createClient"
      | "asProvider",
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}

Source

client-operation.ts

runBucketOperation

Executes a bucket operation through its injectable provider and telemetry boundary.

Example

Effect.provide(
  runBucketOperation({
    operation: "get",
    input: { key: "a" },
    work: (p) => p.get!("a"),
    validate: (v) => v,
  }),
  bucketRuntimeLayer(options),
);

Signature

declare const runBucketOperation: <A>(
  invocation: BucketInvocation<A>,
) => Effect.Effect<
  A,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;

Source

client-operation.types.ts

BucketInvocation (interface)

Complete arguments for one provider invocation.

Example

const invocation: BucketInvocation<boolean> = {
  operation: "exists",
  input: { key: "a" },
  work: (p) => p.exists!("a"),
  validate: Effect.succeed,
};

Signature

export interface BucketInvocation<A> {
  readonly operation: BucketOperation;
  readonly input: unknown;
  readonly capability?: "signedReadUrl" | "signedWriteUrl";
  readonly work: (provider: BucketProvider, context: BucketOperationContext) => Promise<A> | A;
  readonly validate: (value: A) => Effect.Effect<A, BucketProviderFailureError>;
  readonly context?: BucketOperationContext;
}

Source

client-provider.types.ts

BucketCapabilities (interface)

Provider capability flags.

Example

const capabilities: BucketCapabilities = { signedReadUrl: true };

Signature

export interface BucketCapabilities {
  readonly signedReadUrl?: boolean;
  readonly signedWriteUrl?: boolean;
}

Source

BucketCapability (type alias)

Optional signed URL capabilities advertised by a provider.

Example

const capability: BucketCapability = "signedReadUrl";

Signature

type BucketCapability = "signedReadUrl" | "signedWriteUrl";

Source

BucketObjectMetadata (interface)

Portable object metadata returned by a provider.

Example

const metadata: BucketObjectMetadata = { etag: "sha256:abc", size: 3 };

Signature

export interface BucketObjectMetadata {
  readonly etag: string;
  /** Strong content digest when the provider can calculate one. */
  readonly contentHash?: string;
  readonly contentType?: string;
  readonly size?: number;
  readonly metadata?: Readonly<Record<string, string>>;
}

Source

BucketOperation (type alias)

Fixed names for provider operations; safe as telemetry labels.

Example

const operation: BucketOperation = "get";

Signature

type BucketOperation =
  "put" | "get" | "head" | "delete" | "exists" | "list" | "createReadUrl" | "createWriteUrl";

Source

BucketOperationContext (interface)

Per-call context passed to providers.

Example

const signal = context.signal;

Signature

export interface BucketOperationContext {
  readonly operation: BucketOperation;
  readonly signal: AbortSignal;
  readonly deadlineMs?: number;
}

Source

BucketProvider (interface)

Provider implementation; omitted operations fail with BucketProviderError.

Example

const provider: BucketProvider = { get: () => undefined };

Signature

export interface BucketProvider {
  readonly capabilities?: BucketCapabilities | readonly BucketCapability[];
  /** Store an object.
   * @param key - Portable object key.
   * @param bytes - Object content.
   * @param options - Optional content metadata.
   * @param context - Cancellation and deadline context.
   * @returns Completion or a provider rejection.
   * @example await provider.put?.("a", new Uint8Array());
   */
  readonly put?: (
    key: string,
    bytes: Uint8Array,
    options?: BucketPutOptions,
    context?: BucketOperationContext,
  ) => MaybePromise<void>;
  /** Read an object.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Bytes, undefined, or a provider rejection.
   * @example await provider.get?.("a");
   */
  readonly get?: (
    key: string,
    context?: BucketOperationContext,
  ) => MaybePromise<Uint8Array | undefined>;
  /** Read object metadata.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Metadata, undefined, or a provider rejection.
   * @example await provider.head?.("a");
   */
  readonly head?: (
    key: string,
    context?: BucketOperationContext,
  ) => MaybePromise<BucketObjectMetadata | undefined>;
  /** Remove an object.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Completion or a provider rejection.
   * @example await provider.delete?.("a");
   */
  readonly delete?: (key: string, context?: BucketOperationContext) => MaybePromise<void>;
  /** Check whether an object exists.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Existence or a provider rejection.
   * @example await provider.exists?.("a");
   */
  readonly exists?: (key: string, context?: BucketOperationContext) => MaybePromise<boolean>;
  /** List keys in provider order.
   * @param prefix - Optional portable prefix.
   * @param context - Cancellation and deadline context.
   * @returns Ordered keys or a provider rejection.
   * @example await provider.list?.("images/");
   */
  readonly list?: (
    prefix: string | undefined,
    context?: BucketOperationContext,
  ) => MaybePromise<readonly string[]>;
  /** Create a signed read URL.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns URL text or a provider rejection.
   * @example await provider.createReadUrl?.("a");
   */
  readonly createReadUrl?: (key: string, context?: BucketOperationContext) => MaybePromise<string>;
  /** Create a signed write URL.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns URL text or a provider rejection.
   * @example await provider.createWriteUrl?.("a");
   */
  readonly createWriteUrl?: (key: string, context?: BucketOperationContext) => MaybePromise<string>;
}

Source

BucketPutOptions (interface)

Metadata and content type supplied when storing bytes.

Example

const options: BucketPutOptions = { contentType: "image/png" };

Signature

export interface BucketPutOptions extends Readonly<Record<string, unknown>> {
  readonly contentType?: string;
  readonly metadata?: Readonly<Record<string, string>>;
}

Source

client-results.ts

validateBooleanEffect

Check an existence result.

Example

Effect.runSync(validateBooleanEffect(true));

Signature

declare const validateBooleanEffect: (
  value: boolean,
) => Effect.Effect<boolean, BucketProviderFailureError, never>;

Source

validateBytesEffect

Check bytes returned by a provider.

Example

Effect.runSync(validateBytesEffect(new Uint8Array()));

Signature

declare const validateBytesEffect: (
  value: Uint8Array<ArrayBufferLike> | undefined,
) => Effect.Effect<Uint8Array<ArrayBufferLike> | undefined, BucketProviderFailureError, never>;

Source

validateKeysEffect

Check listed keys while retaining provider order.

Example

Effect.runSync(validateKeysEffect(["a", "b"]));

Signature

declare const validateKeysEffect: (
  value: ReadonlyArray<string>,
) => Effect.Effect<Array<string>, BucketProviderFailureError, never>;

Source

validateMetadataEffect

Check metadata returned by a provider.

Example

Effect.runSync(validateMetadataEffect({ etag: "abc" }));

Signature

declare const validateMetadataEffect: (
  value: BucketObjectMetadata | undefined,
) => Effect.Effect<BucketObjectMetadata | undefined, BucketProviderFailureError, never>;

Source

validateUrlEffect

Check a signed URL result.

Example

Effect.runSync(validateUrlEffect("https://example.test/a", "createReadUrl"));

Signature

declare const validateUrlEffect: (
  value: string,
  operation: "createReadUrl" | "createWriteUrl",
) => Effect.Effect<string, BucketProviderFailureError, never>;

Source

client-runtime.ts

BucketRuntime (class)

Injectable provider and invocation configuration.

Example

Effect.provide(getBucketEffect("a"), bucketRuntimeLayer(options));

Signature

declare class BucketRuntime

Source

asProvider

Converts an optional source to a provider while retaining legacy validation.

Throws

BucketProviderError for non-object sources.

Example

asProvider(undefined);

Signature

declare const asProvider: (value: unknown) => BucketProvider;

Source

asProviderEffect

Converts an optional source to a provider in Effect.

Example

Effect.runSync(asProviderEffect(undefined));

Signature

declare const asProviderEffect: (
  value: unknown,
) => Effect.Effect<BucketProvider, BucketProviderError, never>;

Source

bucketRuntimeLayer

Creates a live runtime Layer from compatibility client options.

Example

bucketRuntimeLayer({ ownerId: "job", bucketId: "assets", source: {} });

Signature

declare const bucketRuntimeLayer: (
  options: BucketClientOptions,
) => Layer.Layer<BucketRuntime, BucketProviderError, never>;

Source

client-runtime.types.ts

BucketRuntimeService (interface)

Provider and invocation configuration supplied to bucket Effects.

Example

const runtime: BucketRuntimeService = { options, provider };

Signature

export interface BucketRuntimeService {
  readonly options: BucketClientOptions;
  readonly provider: BucketProvider;
  readonly bridgeOwned?: boolean;
}

Source

client-utils.ts

classifyEffect

Classifies a provider or cancellation failure in Effect.

Example

Effect.runSync(classifyEffect(new BucketOperationCancelledError()));

Signature

declare const classifyEffect: (
  value: unknown,
) => Effect.Effect<BucketOperationOutcome, never, never>;

Source

notifyEffect

Calls an advisory hook without letting it affect provider behavior.

Example

Effect.runSync(notifyEffect((value) => console.log(value), "ready"));

Signature

declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
) => Effect.Effect<void, never, never>;

Source

required

Synchronous compatibility adapter for a required provider method.

Throws

BucketProviderError when absent.

Example

required(provider.get, "get")("a");

Signature

declare const required: <A>(
  value: ((...args: any[]) => MaybePromise<A>) | undefined,
  operation: BucketOperation,
) => (...args: any[]) => MaybePromise<A>;

Source

requiredEffect

Requires an optional provider method in Effect.

Example

Effect.runSync(requiredEffect(provider.get, "get"));

Signature

declare const requiredEffect: <A>(
  value: ((...args: any[]) => MaybePromise<A>) | undefined,
  operation: BucketOperation,
) => Effect.Effect<(...args: any[]) => MaybePromise<A>, BucketProviderError, never>;

Source

supportsEffect

Checks provider-advertised capabilities in Effect.

Example

Effect.runSync(supportsEffect(provider.capabilities, "signedReadUrl"));

Signature

declare const supportsEffect: (
  value: BucketCapabilities | ReadonlyArray<BucketCapability> | undefined,
  capability: BucketCapability,
) => Effect.Effect<boolean, never, never>;

Source

client.ts

“./client.types.js” (namespace export)

Re-exports all named exports from the “./client.types.js” module.

Signature

export * from "./client.types.js";

Source

BucketCapabilityError

Signature

declare const BucketCapabilityError: typeof BucketCapabilityError;

Source

BucketDependencyError

Signature

declare const BucketDependencyError: typeof BucketDependencyError;

Source

BucketOperationCancelledError

Signature

declare const BucketOperationCancelledError: typeof BucketOperationCancelledError;

Source

BucketOperationTimeoutError

Signature

declare const BucketOperationTimeoutError: typeof BucketOperationTimeoutError;

Source

BucketProviderError

Signature

declare const BucketProviderError: typeof BucketProviderError;

Source

BucketProviderFailureError

Signature

declare const BucketProviderFailureError: typeof BucketProviderFailureError;

Source

createBucketClient

Creates the Promise compatibility client over the Effect bucket operations.

Throws

TypeError for invalid owner or bucket identifiers; BucketProviderError for a malformed source.

Example

createBucketClient({ ownerId: "job", bucketId: "assets", source: provider }).get("a");

Signature

declare const createBucketClient: (options: BucketClientOptions) => BucketClient;

Source

createBucketClientEffect

Creates the compatibility client inside Effect with tagged construction failures.

Example

Effect.runSync(createBucketClientEffect({ ownerId: "job", bucketId: "assets", source: {} }));

Signature

declare const createBucketClientEffect: (
  options: BucketClientOptions,
) => Effect.Effect<BucketClient, BucketValidationError | BucketProviderError, never>;

Source

client.types.ts

“./client-provider.types.js” (namespace export)

Re-exports all named exports from the “./client-provider.types.js” module.

Signature

export * from "./client-provider.types.js";

Source

BucketBridgeOptions (interface)

Metadata passed to an optional invocation bridge.

Example

const name = bridgeOptions.name;

Signature

export interface BucketBridgeOptions {
  readonly name: string;
  readonly attributes: Readonly<Record<string, unknown>>;
  readonly signal: AbortSignal;
  readonly input?: unknown;
}

Source

BucketClient (interface)

Promise adapter used by existing RELKIT application code.

Example

await client.get("images/logo.png");

Signature

export interface BucketClient {
  /** Store content.
   * @param key - Portable key.
   * @param bytes - Content.
   * @param options - Optional metadata.
   * @returns Completion Promise or provider failure.
   * @example await client.put("a", new Uint8Array());
   */
  put(key: string, bytes: Uint8Array, options?: BucketPutOptions): Promise<void>;
  /** Read content.
   * @param key - Portable key.
   * @returns Bytes or undefined, or a rejected Promise.
   * @example await client.get("a");
   */
  get(key: string): Promise<Uint8Array | undefined>;
  /** Read metadata.
   * @param key - Portable key.
   * @returns Metadata or undefined, or a rejected Promise.
   * @example await client.head("a");
   */
  head(key: string): Promise<BucketObjectMetadata | undefined>;
  /** Delete content.
   * @param key - Portable key.
   * @returns Completion Promise or provider failure.
   * @example await client.delete("a");
   */
  delete(key: string): Promise<void>;
  /** Test for a key.
   * @param key - Portable key.
   * @returns Existence flag or a rejected Promise.
   * @example await client.exists("a");
   */
  exists(key: string): Promise<boolean>;
  /** List keys in provider order.
   * @param prefix - Optional portable prefix.
   * @returns Keys or a rejected Promise.
   * @example await client.list("images/");
   */
  list(prefix?: string): Promise<readonly string[]>;
  /** Request a signed download URL.
   * @param key - Portable key.
   * @returns URL or a rejected Promise.
   * @example await client.createReadUrl("a");
   */
  createReadUrl(key: string): Promise<string>;
  /** Request a signed upload URL.
   * @param key - Portable key.
   * @returns URL or a rejected Promise.
   * @example await client.createWriteUrl("a");
   */
  createWriteUrl(key: string): Promise<string>;
}

Source

BucketClientOptions (interface)

Configuration for a Promise bucket client.

Example

const options: BucketClientOptions = { ownerId: "job", bucketId: "assets", source: {} };

Signature

export interface BucketClientOptions {
  readonly ownerId: string;
  readonly bucketId: string;
  readonly source: unknown;
  readonly bridge?: BucketInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly declared?: boolean;
  readonly onObservedEdge?: (edge: BucketObservedEdge) => void;
  readonly onOperation?: (operation: BucketOperationObservation) => void;
}

Source

BucketInvocationBridge (interface)

Bridge that owns external invocation instrumentation.

Example

const bridge: BucketInvocationBridge = { run: async (operation) => operation() };

Signature

export interface BucketInvocationBridge {
  /** Invoke an operation through the bridge's tracing and cancellation boundary.
   * @param operation - Provider work to run.
   * @param options - Invocation name, attributes, signal, and input.
   * @returns The operation result or a rejected Promise.
   * @example await bridge.run(() => provider.get!("a"), { name: "bucket.get", attributes: {}, signal });
   */
  readonly run: <A>(operation: () => MaybePromise<A>, options?: BucketBridgeOptions) => Promise<A>;
}

Source

BucketObservedEdge (interface)

Observed function-to-bucket dependency edge.

Example

const edge: BucketObservedEdge = { relationship: "uses-bucket", from: "job", to: "assets" };

Signature

export interface BucketObservedEdge {
  readonly relationship: "uses-bucket";
  readonly from: string;
  readonly to: string;
}

Source

BucketOperationObservation (interface)

Advisory completion signal emitted after a bucket operation.

Example

const outcome = observation.outcome;

Signature

export interface BucketOperationObservation {
  readonly capability: "buckets";
  readonly operation: BucketOperation;
  readonly ownerId: string;
  readonly bucketId: string;
  readonly outcome: BucketOperationOutcome;
}

Source

BucketOperationOutcome (type alias)

Bounded outcome classification emitted to observation hooks.

Signature

type BucketOperationOutcome =
  "success" | "provider-failure" | "cancelled" | "timeout" | "unsupported";

Source

define-bucket.ts

defineBucket

Defines a managed object store with explicit visibility and bounded upload policy.

Throws

TypeError when the authoring input is invalid.

Example

import { defineBucket } from "@relkit/buckets";
const assets = defineBucket({
  id: "assets",
  visibility: "public",
  maxObjectBytes: 1_048_576,
});

Signature

declare const defineBucket: <const Id extends string>(
  options: DefineBucketOptions<Id>,
) => BucketDescriptor<Id>;

Source

Since v0.1.0

“./define-bucket.types.js” (namespace export)

Re-exports all named exports from the “./define-bucket.types.js” module.

Signature

export * from "./define-bucket.types.js";

Source

BucketValidationError

Signature

declare const BucketValidationError: typeof BucketValidationError;

Source

assertBucketDescriptor

Narrows a value to BucketDescriptorAny or throws a compatibility TypeError.

Throws

TypeError when value is invalid.

Example

assertBucketDescriptor(defineBucket({ id: "assets", visibility: "private" }));

Signature

declare const assertBucketDescriptor: (value: unknown) => asserts value is BucketDescriptorAny;

Source

assertBucketDescriptorEffect

Validates a bucket descriptor with a tagged Effect failure.

Example

Effect.runSync(assertBucketDescriptorEffect(defineBucket({ id: "a", visibility: "private" })));

Signature

declare const assertBucketDescriptorEffect: (
  value: unknown,
) => Effect.Effect<void, BucketValidationError, never>;

Source

defineBucketEffect

Defines a bucket in Effect, exposing invalid input as a tagged error.

Example

Effect.runSync(defineBucketEffect({ id: "assets", visibility: "private" }));

Signature

declare const defineBucketEffect: <const Id extends string>(
  options: DefineBucketOptions<Id>,
) => Effect.Effect<BucketDescriptor<Id>, BucketValidationError, never>;

Source

isBucketDescriptor

Checks whether a value is a well-formed bucket descriptor.

Example

isBucketDescriptor(defineBucket({ id: "assets", visibility: "private" }));

Signature

declare const isBucketDescriptor: (value: unknown) => value is BucketDescriptorAny;

Source

isBucketDescriptorEffect

Effectful descriptor predicate for composition inside workflows.

Example

Effect.runSync(isBucketDescriptorEffect({}));

Signature

declare const isBucketDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

define-bucket.types.ts

BucketDescriptor (interface)

Immutable authored bucket descriptor.

Example

const bucket: BucketDescriptor<"assets"> = defineBucket({ id: "assets", visibility: "private" });

Signature

export interface BucketDescriptor<Id extends string> extends DescriptorBase<"bucket", Id> {
  readonly profile?: string;
  readonly visibility: BucketVisibility;
  readonly maxObjectBytes?: number;
  readonly allowedContentTypes?: readonly string[];
}

Source

BucketDescriptorAny (type alias)

Bucket descriptor with an arbitrary stable identifier.

Example

const bucket: BucketDescriptorAny = defineBucket({ id: "assets", visibility: "private" });

Signature

type BucketDescriptorAny = BucketDescriptor<string>;

Source

BucketVisibility (type alias)

Visibility policy for a bucket.

Example

const visibility: BucketVisibility = "private";

Signature

type BucketVisibility = "private" | "public";

Source

DefineBucketOptions (interface)

Input accepted when defining a bucket.

Example

const options: DefineBucketOptions<"assets"> = { id: "assets", visibility: "private" };

Signature

export interface DefineBucketOptions<Id extends string> extends DescriptorMetadata {
  readonly id: Id;
  readonly profile?: string;
  readonly visibility: BucketVisibility;
  readonly maxObjectBytes?: number;
  readonly allowedContentTypes?: readonly string[];
}

Source

index.ts

“./bucket-validation-error.js” (namespace export)

Re-exports all named exports from the “./bucket-validation-error.js” module.

Signature

export * from "./bucket-validation-error.js";

Source

“./client-effects.js” (namespace export)

Re-exports all named exports from the “./client-effects.js” module.

Signature

export * from "./client-effects.js";

Source

“./client-observability.js” (namespace export)

Re-exports all named exports from the “./client-observability.js” module.

Signature

export * from "./client-observability.js";

Source

“./client-runtime.js” (namespace export)

Re-exports all named exports from the “./client-runtime.js” module.

Signature

export * from "./client-runtime.js";

Source

“./client.js” (namespace export)

Re-exports all named exports from the “./client.js” module.

Signature

export * from "./client.js";

Source

“./define-bucket.js” (namespace export)

Re-exports all named exports from the “./define-bucket.js” module.

Signature

export * from "./define-bucket.js";

Source