ocel 0.0.1-alpha.1 → 0.0.1

package/dist/bucket/client.d.ts

@@ -0,0 +1,49 @@
+import type { Bucket } from "./bucket.js";
+import type { AnyUploader, Uploader } from "./types.js";
+type Uploaders<B> = B extends Bucket<infer U> ? U : never;
+type UploaderName<B> = keyof Uploaders<B> & string;
+type InputOf<B, K extends UploaderName<B>> = Uploaders<B>[K] extends Uploader<infer I, any, any> ? I : never;
+type UploadArgs<B, K extends UploaderName<B>> = {
+    files: BrowserFile[];
+} & (InputOf<B, K> extends undefined ? {
+    input?: undefined;
+} : {
+    input: InputOf<B, K>;
+});
+export interface BrowserFile {
+    name: string;
+    size: number;
+    type: string;
+}
+interface FetchResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<any>;
+}
+type FetchLike = (url: string, init?: {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}) => Promise<FetchResponse>;
+export interface UploadClientOptions {
+    url: string;
+    pollIntervalMs?: number;
+    maxPollMs?: number;
+    fetch?: FetchLike;
+}
+export interface UploadResultFile {
+    key: string;
+    name: string;
+}
+export interface UploadCallbacks {
+    onClientUploadComplete?: (result: {
+        files: UploadResultFile[];
+    }) => void;
+    onError?: (error: Error) => void;
+}
+export declare function createUploadClient<B extends Bucket<Record<string, AnyUploader>>>(options: UploadClientOptions): {
+    upload: <K extends UploaderName<B>>(name: K, args: UploadArgs<B, K>, callbacks?: UploadCallbacks) => Promise<{
+        files: UploadResultFile[];
+    }>;
+};
+export {};

package/dist/bucket/client.js

@@ -0,0 +1,95 @@
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const pollCeilingMs = 15_000;
+async function pollUntilTerminal(fetchImpl, baseUrl, sessionId, intervalMs, maxMs) {
+    const deadline = Date.now() + maxMs;
+    let wait = intervalMs;
+    for (;;) {
+        const res = await fetchImpl(`${baseUrl}?op=poll&sessionId=${encodeURIComponent(sessionId)}`);
+        const body = (await res.json());
+        if (body.state === "succeeded" || body.state === "expired")
+            return body;
+        if (Date.now() >= deadline)
+            return { state: "expired" };
+        await sleep(wait);
+        wait = Math.min(wait * 2, pollCeilingMs);
+    }
+}
+export function createUploadClient(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const intervalMs = options.pollIntervalMs ?? 1000;
+    const maxMs = options.maxPollMs ?? 15 * 60 * 1000;
+    async function upload(name, args, callbacks = {}) {
+        try {
+            const presignRes = await fetchImpl(`${options.url}?op=presign`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    uploader: name,
+                    input: args.input,
+                    files: args.files.map((f) => ({
+                        name: f.name,
+                        size: f.size,
+                        mimeType: f.type,
+                    })),
+                }),
+            });
+            if (!presignRes.ok) {
+                throw new Error(`presign failed (${presignRes.status})`);
+            }
+            const presign = (await presignRes.json());
+            await Promise.all(presign.files.map((target, i) => {
+                const method = target.method || "PUT";
+                const file = args.files[i];
+                if (target.fields && Object.keys(target.fields).length > 0) {
+                    const form = new FormData();
+                    for (const [name, value] of Object.entries(target.fields))
+                        form.append(name, value);
+                    if (target.contentDisposition) {
+                        form.append("Content-Disposition", target.contentDisposition);
+                    }
+                    form.append("file", file);
+                    return fetchImpl(target.url, { method, body: form }).then((res) => {
+                        if (!res.ok) {
+                            throw new Error(`upload ${method} failed (${res.status})`);
+                        }
+                    });
+                }
+                const headers = {
+                    ...target.headers,
+                    ...(target.contentDisposition
+                        ? { "content-disposition": target.contentDisposition }
+                        : {}),
+                };
+                return fetchImpl(target.url, {
+                    method,
+                    body: file,
+                    headers,
+                }).then((res) => {
+                    if (!res.ok) {
+                        throw new Error(`upload ${method} failed (${res.status})`);
+                    }
+                });
+            }));
+            await fetchImpl(`${options.url}?op=complete`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ sessionId: presign.sessionId }),
+            });
+            const status = await pollUntilTerminal(fetchImpl, options.url, presign.sessionId, intervalMs, maxMs);
+            if (status.state !== "succeeded") {
+                throw new Error(status.state === "expired" ? "upload expired" : (status.error ?? "upload failed"));
+            }
+            const result = {
+                files: presign.files.map((t) => ({ key: t.key, name: t.name })),
+            };
+            callbacks.onClientUploadComplete?.(result);
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            callbacks.onError?.(error);
+            throw error;
+        }
+    }
+    return { upload };
+}

package/dist/bucket/errors.d.ts

@@ -0,0 +1,12 @@
+/** Thrown when an operation that cannot answer with `null` names an object the bucket does not have. */
+export declare class ObjectNotFoundError extends Error {
+    /** The key that named nothing. */
+    readonly key: string;
+    constructor(key: string);
+}
+/** Thrown when a write set `ifNoneMatch` or `ifMatch` and the object did not meet it. */
+export declare class PreconditionFailedError extends Error {
+    /** The key whose current state refused the write. */
+    readonly key: string;
+    constructor(key: string);
+}

package/dist/bucket/errors.js

@@ -0,0 +1,20 @@
+/** Thrown when an operation that cannot answer with `null` names an object the bucket does not have. */
+export class ObjectNotFoundError extends Error {
+    /** The key that named nothing. */
+    key;
+    constructor(key) {
+        super(`the bucket has no object under "${key}"`);
+        this.name = "ObjectNotFoundError";
+        this.key = key;
+    }
+}
+/** Thrown when a write set `ifNoneMatch` or `ifMatch` and the object did not meet it. */
+export class PreconditionFailedError extends Error {
+    /** The key whose current state refused the write. */
+    key;
+    constructor(key) {
+        super(`the object under "${key}" did not meet the condition this write set`);
+        this.name = "PreconditionFailedError";
+        this.key = key;
+    }
+}

package/dist/bucket/express.d.ts

@@ -0,0 +1,10 @@
+import type { Request as ExpressRequest, RequestHandler } from "express";
+import type { z } from "zod";
+import type { Bucket } from "./bucket.js";
+import { type RouteOptions } from "./route.js";
+import type { ParsedInput, Uploader, UploaderAuth, UploaderUpload } from "./types.js";
+export { Bucket, type BucketOptions, bucket } from "./bucket.js";
+export type { RouteOptions } from "./route.js";
+export type { CompletedFile, FileInfo, Limits, PathConfig, Uploader, } from "./types.js";
+export declare function uploader<TInput extends z.ZodType | undefined = undefined, TMetadata = unknown>(auth: UploaderAuth<ExpressRequest, TInput, TMetadata>, upload?: UploaderUpload<TMetadata>): Uploader<ParsedInput<TInput>, TMetadata, ExpressRequest>;
+export declare function createRouteHandler(bucket: Bucket, options?: RouteOptions): RequestHandler;

package/dist/bucket/express.js

@@ -0,0 +1,24 @@
+import { createRouteHandler as coreCreateRouteHandler } from "./route.js";
+import { uploader as coreUploader } from "./uploader.js";
+export { Bucket, bucket } from "./bucket.js";
+export function uploader(auth, upload) {
+    return coreUploader(auth, upload);
+}
+async function sendResponse(res, webRes) {
+    res.status(webRes.status);
+    webRes.headers.forEach((value, key) => {
+        res.setHeader(key, value);
+    });
+    res.end(Buffer.from(await webRes.arrayBuffer()));
+}
+export function createRouteHandler(bucket, options) {
+    const { GET, POST } = coreCreateRouteHandler(bucket, options);
+    return (req, res, next) => {
+        if (req.originalUrl)
+            req.url = req.originalUrl;
+        const handler = req.method === "GET" ? GET : POST;
+        handler(req)
+            .then((webRes) => sendResponse(res, webRes))
+            .catch(next);
+    };
+}

package/dist/bucket/hono.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+import type { Bucket } from "./bucket.js";
+import { type RouteOptions } from "./route.js";
+import type { MaybePromise, ParsedInput, Uploader, UploaderUpload } from "./types.js";
+export { Bucket, type BucketOptions, bucket } from "./bucket.js";
+export type { RouteOptions } from "./route.js";
+export type { CompletedFile, FileInfo, Limits, PathConfig, Uploader, } from "./types.js";
+export interface HonoUploaderAuth<TInput extends z.ZodType | undefined, TMetadata> {
+    input?: TInput;
+    middleware: (ctx: {
+        c: Context;
+        input: ParsedInput<TInput>;
+    }) => MaybePromise<TMetadata>;
+}
+export declare function uploader<TInput extends z.ZodType | undefined = undefined, TMetadata = unknown>(auth: HonoUploaderAuth<TInput, TMetadata>, upload?: UploaderUpload<TMetadata>): Uploader<ParsedInput<TInput>, TMetadata, Context>;
+export type HonoRouteHandler = (c: Context) => Promise<Response>;
+export declare function createRouteHandler(bucket: Bucket, options?: RouteOptions): HonoRouteHandler;

package/dist/bucket/hono.js

@@ -0,0 +1,13 @@
+import { createRouteHandler as coreCreateRouteHandler } from "./route.js";
+import { uploader as coreUploader } from "./uploader.js";
+export { Bucket, bucket } from "./bucket.js";
+export function uploader(auth, upload) {
+    return coreUploader({
+        input: auth.input,
+        middleware: ({ req, input }) => auth.middleware({ c: req, input }),
+    }, upload);
+}
+export function createRouteHandler(bucket, options) {
+    const { GET, POST } = coreCreateRouteHandler(bucket, options);
+    return (c) => (c.req.method === "GET" ? GET(c.req.raw) : POST(c.req.raw, c));
+}

package/dist/bucket/index.d.ts

@@ -0,0 +1,8 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export { Bucket, type BucketOptions, bucket } from "./bucket.js";
+export { type BucketContext, resolveBucketContext, } from "./bucket-context.js";
+export { ObjectNotFoundError, PreconditionFailedError } from "./errors.js";
+export type { GetOptions, ListOptions, ObjectBody, ObjectInfo, ObjectListing, ObjectPage, PutBody, PutOptions, SignedUpload, SignedUploadOptions, SignedUrlOptions, } from "./objects.js";
+export { createRouteHandler, type RouteHandlers, type RouteOptions, } from "./route.js";
+export type { AnyUploader, CompletedFile, FileInfo, Limits, PathConfig, Uploader, UploaderAuth, UploaderUpload, UploadRequest, } from "./types.js";
+export { uploader } from "./uploader.js";

package/dist/bucket/index.js

@@ -0,0 +1,6 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export { Bucket, bucket } from "./bucket.js";
+export { resolveBucketContext, } from "./bucket-context.js";
+export { ObjectNotFoundError, PreconditionFailedError } from "./errors.js";
+export { createRouteHandler, } from "./route.js";
+export { uploader } from "./uploader.js";

package/dist/bucket/keys.d.ts

@@ -0,0 +1,5 @@
+import type { FileInfo, PathConfig } from "./types.js";
+export declare function generateKey(path: PathConfig<unknown> | undefined, ctx: {
+    file: FileInfo;
+    metadata: unknown;
+}): string;

package/dist/bucket/keys.js

@@ -0,0 +1,24 @@
+function randomToken() {
+    return crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+}
+function sanitize(name) {
+    const base = name.split(/[\\/]/).pop() ?? name;
+    return base.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/^\.+/, "");
+}
+function withSuffix(name, token) {
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0)
+        return `${name}-${token}`;
+    return `${name.slice(0, dot)}-${token}${name.slice(dot)}`;
+}
+export function generateKey(path, ctx) {
+    if (typeof path === "function") {
+        return path(ctx);
+    }
+    const prefix = path?.prefix ?? "";
+    let name = sanitize(ctx.file.name);
+    if (path?.randomSuffix) {
+        name = withSuffix(name, randomToken());
+    }
+    return `${prefix}${name}`;
+}

package/dist/bucket/metadata.d.ts

@@ -0,0 +1,6 @@
+export interface MetadataEnvelope {
+    uploader: string;
+    metadata: unknown;
+}
+export declare function encodeMetadata(envelope: MetadataEnvelope): Uint8Array;
+export declare function decodeMetadata(bytes: Uint8Array): MetadataEnvelope;

package/dist/bucket/metadata.js

@@ -0,0 +1,6 @@
+export function encodeMetadata(envelope) {
+    return new TextEncoder().encode(JSON.stringify(envelope));
+}
+export function decodeMetadata(bytes) {
+    return JSON.parse(new TextDecoder().decode(bytes));
+}

package/dist/bucket/next.d.ts

@@ -0,0 +1,15 @@
+import "./server-only.js";
+import type { NextRequest } from "next/server";
+import type { z } from "zod";
+import type { Bucket } from "./bucket.js";
+import { type RouteOptions } from "./route.js";
+import type { ParsedInput, Uploader, UploaderAuth, UploaderUpload } from "./types.js";
+export { Bucket, type BucketOptions, bucket } from "./bucket.js";
+export type { RouteOptions } from "./route.js";
+export type { CompletedFile, FileInfo, Limits, PathConfig, Uploader, } from "./types.js";
+export declare function uploader<TInput extends z.ZodType | undefined = undefined, TMetadata = unknown>(auth: UploaderAuth<NextRequest, TInput, TMetadata>, upload?: UploaderUpload<TMetadata>): Uploader<ParsedInput<TInput>, TMetadata, NextRequest>;
+export interface NextRouteHandlers {
+    GET: (req: NextRequest) => Promise<Response>;
+    POST: (req: NextRequest) => Promise<Response>;
+}
+export declare function createRouteHandler(bucket: Bucket, options?: RouteOptions): NextRouteHandlers;

package/dist/bucket/next.js

@@ -0,0 +1,11 @@
+import "./server-only.js";
+import { createRouteHandler as coreCreateRouteHandler } from "./route.js";
+import { uploader as coreUploader } from "./uploader.js";
+export { Bucket, bucket } from "./bucket.js";
+export function uploader(auth, upload) {
+    return coreUploader(auth, upload);
+}
+export function createRouteHandler(bucket, options) {
+    const { GET, POST } = coreCreateRouteHandler(bucket, options);
+    return { GET, POST };
+}

package/dist/bucket/objects.d.ts

@@ -0,0 +1,130 @@
+import type { BucketContext } from "./bucket-context.js";
+/** What a bucket knows about one of its objects. */
+export interface ObjectInfo {
+    /** The key the object is addressed by. */
+    key: string;
+    /** The object's length in bytes. */
+    size: number;
+    /** The store's opaque version tag for these bytes. */
+    etag: string;
+    /** The media type the object was written with. */
+    contentType: string;
+    /** When the object last took its current bytes, where the store reports it. */
+    uploadedAt: Date | undefined;
+    /** The user metadata written alongside the object. */
+    metadata: Record<string, string>;
+}
+/** An object's bytes, with the info that came back beside them. */
+export interface ObjectBody {
+    /** What the bucket knows about the object. */
+    info: ObjectInfo;
+    /** The bytes, as a stream that may be read once. */
+    body: ReadableStream<Uint8Array>;
+    /** The bytes decoded as UTF-8. */
+    text(): Promise<string>;
+    /** The bytes parsed as JSON. */
+    json<T = unknown>(): Promise<T>;
+    /** The bytes. */
+    bytes(): Promise<Uint8Array>;
+}
+/** A body a caller may hand to `put`. */
+export type PutBody = string | Uint8Array | Blob | ReadableStream<Uint8Array>;
+/** How a write is conditioned and described. */
+export interface PutOptions {
+    /** The media type to store the object under. */
+    contentType?: string;
+    /** The cache-control the store should serve the object with. */
+    cacheControl?: string;
+    /** User metadata to keep beside the object, capped at 2 KB. */
+    metadata?: Record<string, string>;
+    /** `"*"` writes only when no object exists under the key. */
+    ifNoneMatch?: "*";
+    /** Writes only when the object's current etag matches. */
+    ifMatch?: string;
+    /** Abandons the write, including every part in flight. */
+    signal?: AbortSignal;
+}
+/** Which bytes of an object to read. */
+export interface GetOptions {
+    /** The byte range to read; `length` omitted reads to the end. */
+    range?: {
+        offset: number;
+        length?: number;
+    };
+}
+/** How a listing is bounded. */
+export interface ListOptions {
+    /** Only keys under this prefix. */
+    prefix?: string;
+    /** How many objects one page contains, at most 1000. */
+    limit?: number;
+}
+/** One page of a listing. */
+export interface ObjectPage {
+    /** The objects on this page. */
+    objects: ObjectInfo[];
+    /** The cursor that continues the listing, empty when this was the last page. */
+    cursor: string;
+}
+/** A listing, walked as an async iterable or one page at a time. */
+export interface ObjectListing extends AsyncIterable<ObjectInfo> {
+    /** One page, starting at `cursor` when given. */
+    page(options?: {
+        cursor?: string;
+    }): Promise<ObjectPage>;
+}
+/** How a signed read is bounded. */
+export interface SignedUrlOptions {
+    /** How long the url stays valid, in seconds. */
+    expiresIn?: number;
+    /** Serves the object as a download, under this filename when a string. */
+    download?: boolean | string;
+}
+/** How a signed write is bounded. */
+export interface SignedUploadOptions {
+    /** How long the target stays valid, in seconds. */
+    expiresIn?: number;
+    /** The largest body the target accepts, in bytes. */
+    maxSize?: number;
+    /** The media type the target accepts. */
+    contentType?: string;
+}
+/** A target an uploader drives itself. */
+export interface SignedUpload {
+    /** Where to send the body. */
+    url: string;
+    /** The HTTP method to send it with. */
+    method: string;
+    /** Headers the signature covers, which the caller must send unchanged. */
+    headers: Record<string, string>;
+    /** Form fields a POST upload sends with the body; empty for a PUT target. */
+    fields: Record<string, string>;
+}
+/** The object operations a bucket handle exposes. */
+export interface BucketObjects {
+    /** Writes `body` under `key`, in one request or in parts, and returns the stored object. */
+    put(key: string, body: PutBody, options?: PutOptions): Promise<ObjectInfo>;
+    /** Reads the object under `key`, or `null` when the bucket has none. */
+    get(key: string, options?: GetOptions): Promise<ObjectBody | null>;
+    /** What the bucket knows about `key`, or `null` when it has none. */
+    head(key: string): Promise<ObjectInfo | null>;
+    /** Removes one key or many; a key that is not there is not an error. */
+    delete(key: string | string[]): Promise<void>;
+    /** The objects under a prefix. */
+    list(options?: ListOptions): ObjectListing;
+    /** Copies `source` to `destination` within the bucket. */
+    copy(source: string, destination: string): Promise<ObjectInfo>;
+    /** A url that reads `key` without a credential, for as long as it is valid. */
+    signedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    /** A target that writes `key` without a credential, for as long as it is valid. */
+    signedUpload(key: string, options?: SignedUploadOptions): Promise<SignedUpload>;
+    /** The object's address on a bucket declared `public: true`. */
+    publicUrl(key: string): string;
+}
+type FetchLike = typeof globalThis.fetch;
+/** Builds the object operations against a resolved runtime context. */
+export declare function createObjects(deps: {
+    runtime: () => BucketContext;
+    fetch?: FetchLike;
+}): BucketObjects;
+export {};