@beignet/core/dist/ports/storage.d.ts

Core framework primitives for Beignet

/**
 * Object visibility understood by storage ports.
 */
export type StorageVisibility = "private" | "public";
/**
 * String metadata stored alongside an object.
 */
export type StorageMetadata = Record<string, string>;
/**
 * Body types accepted by `StoragePort.put(...)`.
 */
export type StorageBody = string | ArrayBuffer | Uint8Array | Blob | ReadableStream<Uint8Array>;
/**
 * Options for writing an object to storage.
 */
export interface StoragePutOptions {
    /**
     * MIME content type stored with the object.
     */
    contentType?: string;
    /**
     * Cache-Control value stored with the object.
     */
    cacheControl?: string;
    /**
     * Provider metadata stored with the object.
     */
    metadata?: StorageMetadata;
    /**
     * Whether the object may receive a public URL.
     */
    visibility?: StorageVisibility;
}
/**
 * Metadata for an object in storage.
 */
export interface StorageObject {
    /**
     * Object key. Keys are relative object-store paths, not filesystem paths or
     * public URLs.
     */
    key: string;
    /**
     * Object size in bytes.
     */
    size: number;
    contentType?: string;
    cacheControl?: string;
    /**
     * Provider metadata stored with the object.
     */
    metadata: StorageMetadata;
    /**
     * Object visibility.
     */
    visibility: StorageVisibility;
    /**
     * Last modification timestamp.
     */
    lastModified: Date;
}
/**
 * Object metadata plus a one-shot readable body.
 *
 * Like Fetch response bodies, storage bodies can be consumed once. Call `get`
 * again if you need another reader.
 */
export interface StorageObjectBody extends StorageObject {
    /**
     * Whether this object body has already been consumed. Like Fetch response
     * bodies, storage bodies are one-shot so providers can stream objects without
     * buffering them.
     */
    readonly bodyUsed: boolean;
    /**
     * Discard an unread body and release any resources held by its provider.
     *
     * Calling this after consumption has started is a no-op. Callers that only
     * inspect object metadata should cancel the body in a `finally` block.
     */
    cancel(reason?: unknown): Promise<void>;
    /**
     * Consume the object as a readable byte stream.
     */
    stream(): ReadableStream<Uint8Array>;
    /**
     * Consume the object as bytes.
     */
    bytes(): Promise<Uint8Array>;
    /**
     * Consume the object as an ArrayBuffer.
     */
    arrayBuffer(): Promise<ArrayBuffer>;
    /**
     * Consume the object as UTF-8 text.
     */
    text(): Promise<string>;
}
/**
 * App-facing object storage port.
 *
 * Implement this with S3, R2, local disk, or a test adapter. Application code
 * should depend on this interface instead of provider-specific SDKs.
 */
export interface StoragePort {
    /**
     * Store an object and return its metadata.
     */
    put(key: string, body: StorageBody, options?: StoragePutOptions): Promise<StorageObject>;
    /**
     * Return object metadata and body, or `null` when missing.
     */
    get(key: string): Promise<StorageObjectBody | null>;
    /**
     * Return object metadata without its body, or `null` when missing.
     */
    stat(key: string): Promise<StorageObject | null>;
    /**
     * Delete an object.
     *
     * @returns `true` when the object existed.
     */
    delete(key: string): Promise<boolean>;
    /**
     * Return whether an object exists.
     */
    exists(key: string): Promise<boolean>;
    /**
     * Return a public URL when the object is public and the adapter can build one.
     */
    publicUrl(key: string): Promise<string | null>;
}
/**
 * Options for prefixing one validated storage key.
 */
export interface PrefixStorageKeyOptions {
    /**
     * Optional app or environment prefix. Leading and trailing slashes are
     * removed before it is applied.
     */
    keyPrefix?: string;
    /**
     * Relative object key to prefix.
     */
    key: string;
}
/**
 * Options for formatting a public storage URL.
 */
export interface CreateStoragePublicUrlOptions {
    /**
     * Absolute or app-relative public base URL.
     */
    publicBaseUrl: string;
    /**
     * Relative object key appended to the public base URL.
     */
    key: string;
}
/**
 * Assert that a storage key follows Beignet's provider-neutral key rules.
 *
 * Valid keys are non-empty relative object paths. They do not contain control
 * characters, backslashes, empty path segments, or `.` / `..` segments.
 * Providers may enforce additional adapter-specific restrictions after this
 * shared assertion.
 */
export declare function assertValidStorageKey(key: string): void;
/**
 * Normalize and validate an optional storage key prefix.
 *
 * Empty and slash-only prefixes normalize to an empty string.
 */
export declare function normalizeStorageKeyPrefix(prefix: string | undefined): string;
/**
 * Prefix a storage key with an optional app or environment namespace.
 */
export declare function prefixStorageKey({ keyPrefix, key, }: PrefixStorageKeyOptions): string;
/**
 * Format an encoded public URL for a validated storage key.
 */
export declare function createStoragePublicUrl({ publicBaseUrl, key, }: CreateStoragePublicUrlOptions): string;
/**
 * Options for `createMemoryStorage(...)`.
 */
export interface MemoryStorageOptions {
    /**
     * Base URL used by `publicUrl(...)` for objects written with
     * `visibility: "public"`.
     */
    publicBaseUrl?: string;
}
/**
 * Create an in-memory object storage adapter for tests, examples, and
 * single-process development.
 *
 * This adapter validates object keys using Beignet's storage key rules. It is
 * not durable and does not share objects across processes.
 *
 * @param options - Optional public URL base for public objects.
 * @returns A storage port backed by a local `Map`.
 */
export declare function createMemoryStorage(options?: MemoryStorageOptions): StoragePort;
//# sourceMappingURL=storage.d.ts.map