---
title: Buckets API
description: Generated public TypeScript reference for @relkit/buckets.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineBucket](/docs/api/buckets#definebucket)

For configuration and examples, read [define](/docs/modules/storage/define), [organization](/docs/modules/service/organization), [uploads](/docs/modules/http/uploads).

For a complete workflow, follow [upload product images](/guides/storage/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.

| API                                                                                    | Kind  | Import from       | Example                                                               |
| -------------------------------------------------------------------------------------- | ----- | ----------------- | --------------------------------------------------------------------- |
| [asProvider](/docs/api/buckets#asprovider)                                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#asprovider)                           |
| [asProviderEffect](/docs/api/buckets#asprovidereffect)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#asprovidereffect)                     |
| [assertBucketDescriptor](/docs/api/buckets#assertbucketdescriptor)                     | Value | `@relkit/buckets` | [API example](/docs/api/buckets#assertbucketdescriptor)               |
| [assertBucketDescriptorEffect](/docs/api/buckets#assertbucketdescriptoreffect)         | Value | `@relkit/buckets` | [API example](/docs/api/buckets#assertbucketdescriptoreffect)         |
| [BucketBridgeOptions](/docs/api/buckets#bucketbridgeoptions-interface)                 | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketbridgeoptions-interface)        |
| [BucketCapabilities](/docs/api/buckets#bucketcapabilities-interface)                   | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketcapabilities-interface)         |
| [BucketCapability](/docs/api/buckets#bucketcapability-type-alias)                      | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketcapability-type-alias)          |
| [BucketCapabilityError](/docs/api/buckets#bucketcapabilityerror-class)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketcapabilityerror-class)          |
| [BucketClient](/docs/api/buckets#bucketclient-interface)                               | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketclient-interface)               |
| [BucketClientOptions](/docs/api/buckets#bucketclientoptions-interface)                 | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketclientoptions-interface)        |
| [BucketDependencyError](/docs/api/buckets#bucketdependencyerror-class)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketdependencyerror-class)          |
| [BucketDescriptor](/docs/api/buckets#bucketdescriptor-interface)                       | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketdescriptor-interface)           |
| [BucketDescriptorAny](/docs/api/buckets#bucketdescriptorany-type-alias)                | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketdescriptorany-type-alias)       |
| [BucketInvocationBridge](/docs/api/buckets#bucketinvocationbridge-interface)           | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketinvocationbridge-interface)     |
| [BucketObjectMetadata](/docs/api/buckets#bucketobjectmetadata-interface)               | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketobjectmetadata-interface)       |
| [BucketObservedEdge](/docs/api/buckets#bucketobservededge-interface)                   | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketobservededge-interface)         |
| [BucketOperation](/docs/api/buckets#bucketoperation-type-alias)                        | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperation-type-alias)           |
| [BucketOperationCancelledError](/docs/api/buckets#bucketoperationcancellederror-class) | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationcancellederror-class)  |
| [BucketOperationContext](/docs/api/buckets#bucketoperationcontext-interface)           | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationcontext-interface)     |
| [BucketOperationObservation](/docs/api/buckets#bucketoperationobservation-interface)   | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationobservation-interface) |
| [BucketOperationOutcome](/docs/api/buckets#bucketoperationoutcome-type-alias)          | Type  | `@relkit/buckets` | [Module example](/docs/modules/storage/define)                        |
| [BucketOperationTimeoutError](/docs/api/buckets#bucketoperationtimeouterror-class)     | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationtimeouterror-class)    |
| [BucketProvider](/docs/api/buckets#bucketprovider-interface)                           | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketprovider-interface)             |
| [BucketProviderError](/docs/api/buckets#bucketprovidererror-class)                     | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketprovidererror-class)            |
| [BucketProviderFailureError](/docs/api/buckets#bucketproviderfailureerror-class)       | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketproviderfailureerror-class)     |
| [BucketPutOptions](/docs/api/buckets#bucketputoptions-interface)                       | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketputoptions-interface)           |
| [BucketRuntime](/docs/api/buckets#bucketruntime-class)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketruntime-class)                  |
| [bucketRuntimeLayer](/docs/api/buckets#bucketruntimelayer)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketruntimelayer)                   |
| [BucketTelemetry](/docs/api/buckets#buckettelemetry-class)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#buckettelemetry-class)                |
| [BucketTelemetryLive](/docs/api/buckets#buckettelemetrylive)                           | Value | `@relkit/buckets` | [API example](/docs/api/buckets#buckettelemetrylive)                  |
| [BucketValidationError](/docs/api/buckets#bucketvalidationerror-class)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketvalidationerror-class)          |
| [BucketVisibility](/docs/api/buckets#bucketvisibility-type-alias)                      | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketvisibility-type-alias)          |
| [createBucketClient](/docs/api/buckets#createbucketclient)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketclient)                   |
| [createBucketClientEffect](/docs/api/buckets#createbucketclienteffect)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketclienteffect)             |
| [createBucketReadUrlEffect](/docs/api/buckets#createbucketreadurleffect)               | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketreadurleffect)            |
| [createBucketWriteUrlEffect](/docs/api/buckets#createbucketwriteurleffect)             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketwriteurleffect)           |
| [defineBucket](/docs/api/buckets#definebucket)                                         | Value | `@relkit/buckets` | [API example](/docs/api/buckets#definebucket)                         |
| [defineBucketEffect](/docs/api/buckets#definebucketeffect)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#definebucketeffect)                   |
| [DefineBucketOptions](/docs/api/buckets#definebucketoptions-interface)                 | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#definebucketoptions-interface)        |
| [deleteBucketEffect](/docs/api/buckets#deletebucketeffect)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#deletebucketeffect)                   |
| [existsBucketEffect](/docs/api/buckets#existsbucketeffect)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#existsbucketeffect)                   |
| [getBucketEffect](/docs/api/buckets#getbucketeffect)                                   | Value | `@relkit/buckets` | [API example](/docs/api/buckets#getbucketeffect)                      |
| [headBucketEffect](/docs/api/buckets#headbucketeffect)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#headbucketeffect)                     |
| [isBucketDescriptor](/docs/api/buckets#isbucketdescriptor)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#isbucketdescriptor)                   |
| [isBucketDescriptorEffect](/docs/api/buckets#isbucketdescriptoreffect)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#isbucketdescriptoreffect)             |
| [listBucketEffect](/docs/api/buckets#listbucketeffect)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#listbucketeffect)                     |
| [observeBucket](/docs/api/buckets#observebucket)                                       | Value | `@relkit/buckets` | [API example](/docs/api/buckets#observebucket)                        |
| [putBucketEffect](/docs/api/buckets#putbucketeffect)                                   | Value | `@relkit/buckets` | [API example](/docs/api/buckets#putbucketeffect)                      |

## `bucket-validation-error.ts`

### BucketValidationError (class)

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

**Example**

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

**Signature**

```ts
declare class BucketValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/bucket-validation-error.ts#L7)

## `client-abort.ts`

### runAbortableEffect

Runs provider work with a scoped abort listener and deadline.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-abort.ts#L11)

## `client-effects.ts`

### createBucketReadUrlEffect

Creates a signed read URL when supported.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L141)

### createBucketWriteUrlEffect

Creates a signed write URL when supported.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L162)

### deleteBucketEffect

Deletes one key.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L84)

### existsBucketEffect

Checks whether one key exists.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L103)

### getBucketEffect

Reads bytes for one key.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L46)

### headBucketEffect

Reads metadata for one key.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L65)

### listBucketEffect

Lists keys under an optional prefix.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L122)

### putBucketEffect

Stores bytes under a portable key.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L23)

## `client-errors.ts`

### BucketCapabilityError (class)

An operation requires a capability absent from the provider.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L9)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_CAPABILITY_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L13)

### BucketDependencyError (class)

A function used a bucket without declaring its dependency.

**Example**

```ts
new BucketDependencyError("assets");
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L26)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_DEPENDENCY_UNDECLARED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L30)

### BucketOperationCancelledError (class)

The caller's signal cancelled a bucket operation.

**Example**

```ts
new BucketOperationCancelledError();
```

**Signature**

```ts
declare class BucketOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L62)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L66)

### BucketOperationTimeoutError (class)

A deadline expired before a bucket operation completed.

**Example**

```ts
new BucketOperationTimeoutError();
```

**Signature**

```ts
declare class BucketOperationTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L81)

### code (property)

**Signature**

```ts
readonly code: "ETIMEDOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L85)

### BucketProviderError (class)

A provider omitted a requested operation.

**Example**

```ts
new BucketProviderError("get");
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L43)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_PROVIDER_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L47)

### BucketProviderFailureError (class)

Provider rejection or malformed provider output.

**Example**

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

**Signature**

```ts
declare class BucketProviderFailureError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L101)

## `client-key.ts`

### assertKey

Synchronous compatibility key assertion.

**Throws**

TypeError when invalid.

**Example**

```ts
assertKey("images/logo.png");
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L45)

### assertPrefix

Synchronous compatibility prefix assertion.

**Throws**

TypeError when invalid.

**Example**

```ts
assertPrefix("images/");
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L55)

### validateKeyEffect

Validate a portable object key in Effect.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L9)

### validatePrefixEffect

Validate a portable prefix in Effect.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L18)

### validateTextIdEffect

Validate nonempty identifying text in Effect.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L28)

## `client-observability.ts`

### BucketTelemetry (class)

Injectable observer for bucket Effect operations.

**Example**

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

**Signature**

```ts
declare class BucketTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.ts#L8)

### BucketTelemetryLive

Live bucket spans and bounded Effect metrics.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.ts#L15)

### observeBucket

Measures an operation using fixed operation labels.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.ts#L29)

## `client-observability.types.ts`

### BucketTelemetryService (interface)

Substitutable observation boundary for bucket operations.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.types.ts#L7)

## `client-operation.ts`

### runBucketOperation

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

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-operation.ts#L19)

## `client-operation.types.ts`

### BucketInvocation (interface)

Complete arguments for one provider invocation.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-operation.types.ts#L8)

## `client-provider.types.ts`

### BucketCapabilities (interface)

Provider capability flags.

**Example**

```ts
const capabilities: BucketCapabilities = { signedReadUrl: true };
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L17)

### BucketCapability (type alias)

Optional signed URL capabilities advertised by a provider.

**Example**

```ts
const capability: BucketCapability = "signedReadUrl";
```

**Signature**

```ts
type BucketCapability = "signedReadUrl" | "signedWriteUrl";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L12)

### BucketObjectMetadata (interface)

Portable object metadata returned by a provider.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L34)

### BucketOperation (type alias)

Fixed names for provider operations; safe as telemetry labels.

**Example**

```ts
const operation: BucketOperation = "get";
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L6)

### BucketOperationContext (interface)

Per-call context passed to providers.

**Example**

```ts
const signal = context.signal;
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L25)

### BucketProvider (interface)

Provider implementation; omitted operations fail with BucketProviderError.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L54)

### BucketPutOptions (interface)

Metadata and content type supplied when storing bytes.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L46)

## `client-results.ts`

### validateBooleanEffect

Check an existence result.

**Example**

```ts
Effect.runSync(validateBooleanEffect(true));
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L40)

### validateBytesEffect

Check bytes returned by a provider.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L14)

### validateKeysEffect

Check listed keys while retaining provider order.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L53)

### validateMetadataEffect

Check metadata returned by a provider.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L27)

### validateUrlEffect

Check a signed URL result.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L67)

## `client-runtime.ts`

### BucketRuntime (class)

Injectable provider and invocation configuration.

**Example**

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

**Signature**

```ts
declare class BucketRuntime
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L10)

### asProvider

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

**Throws**

BucketProviderError for non-object sources.

**Example**

```ts
asProvider(undefined);
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L50)

### asProviderEffect

Converts an optional source to a provider in Effect.

**Example**

```ts
Effect.runSync(asProviderEffect(undefined));
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L33)

### bucketRuntimeLayer

Creates a live runtime Layer from compatibility client options.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L19)

## `client-runtime.types.ts`

### BucketRuntimeService (interface)

Provider and invocation configuration supplied to bucket Effects.

**Example**

```ts
const runtime: BucketRuntimeService = { options, provider };
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.types.ts#L6)

## `client-utils.ts`

### classifyEffect

Classifies a provider or cancellation failure in Effect.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L67)

### notifyEffect

Calls an advisory hook without letting it affect provider behavior.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L84)

### required

Synchronous compatibility adapter for a required provider method.

**Throws**

BucketProviderError when absent.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L37)

### requiredEffect

Requires an optional provider method in Effect.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L22)

### supportsEffect

Checks provider-advertised capabilities in Effect.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L52)

## `client.ts`

### "./client.types.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L35)

### BucketCapabilityError

**Signature**

```ts
declare const BucketCapabilityError: typeof BucketCapabilityError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L28)

### BucketDependencyError

**Signature**

```ts
declare const BucketDependencyError: typeof BucketDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L29)

### BucketOperationCancelledError

**Signature**

```ts
declare const BucketOperationCancelledError: typeof BucketOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L30)

### BucketOperationTimeoutError

**Signature**

```ts
declare const BucketOperationTimeoutError: typeof BucketOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L31)

### BucketProviderError

**Signature**

```ts
declare const BucketProviderError: typeof BucketProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L32)

### BucketProviderFailureError

**Signature**

```ts
declare const BucketProviderFailureError: typeof BucketProviderFailureError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L33)

### 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**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L43)

### createBucketClientEffect

Creates the compatibility client inside Effect with tagged construction failures.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L56)

## `client.types.ts`

### "./client-provider.types.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L8)

### BucketBridgeOptions (interface)

Metadata passed to an optional invocation bridge.

**Example**

```ts
const name = bridgeOptions.name;
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L71)

### BucketClient (interface)

Promise adapter used by existing RELKIT application code.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L16)

### BucketClientOptions (interface)

Configuration for a Promise bucket client.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L110)

### BucketInvocationBridge (interface)

Bridge that owns external invocation instrumentation.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L80)

### BucketObservedEdge (interface)

Observed function-to-bucket dependency edge.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L92)

### BucketOperationObservation (interface)

Advisory completion signal emitted after a bucket operation.

**Example**

```ts
const outcome = observation.outcome;
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L100)

### BucketOperationOutcome (type alias)

Bounded outcome classification emitted to observation hooks.

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L11)

## `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**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L36)

Since v0.1.0

### "./define-bucket.types.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L17)

### BucketValidationError

**Signature**

```ts
declare const BucketValidationError: typeof BucketValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L18)

### assertBucketDescriptor

Narrows a value to BucketDescriptorAny or throws a compatibility TypeError.

**Throws**

TypeError when value is invalid.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L177)

### assertBucketDescriptorEffect

Validates a bucket descriptor with a tagged Effect failure.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L186)

### defineBucketEffect

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

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L47)

### isBucketDescriptor

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

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L124)

### isBucketDescriptorEffect

Effectful descriptor predicate for composition inside workflows.

**Example**

```ts
Effect.runSync(isBucketDescriptorEffect({}));
```

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L133)

## `define-bucket.types.ts`

### BucketDescriptor (interface)

Immutable authored bucket descriptor.

**Example**

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L11)

### BucketDescriptorAny (type alias)

Bucket descriptor with an arbitrary stable identifier.

**Example**

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

**Signature**

```ts
type BucketDescriptorAny = BucketDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L21)

### BucketVisibility (type alias)

Visibility policy for a bucket.

**Example**

```ts
const visibility: BucketVisibility = "private";
```

**Signature**

```ts
type BucketVisibility = "private" | "public";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L6)

### DefineBucketOptions (interface)

Input accepted when defining a bucket.

**Example**

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

**Signature**

```ts
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](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L26)

## `index.ts`

### "./bucket-validation-error.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L2)

### "./client-effects.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L4)

### "./client-observability.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L6)

### "./client-runtime.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L5)

### "./client.js" (namespace export)

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

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L3)

### "./define-bucket.js" (namespace export)

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

**Signature**

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

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L1)