@kutur-kit/assets 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kutur Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# @kutur-kit/assets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed file storage for Effect. An asset declares its bucket, its keys, the content types it accepts and its maximum size. Storage is a Layer per bucket: memory, a directory, S3-compatible storage or an R2 bucket through [alchemy](https://alchemy.run). Clients can upload and download through signed URLs, and objects of public buckets get URLs under a CDN or public domain.
+
+Tested with Effect 4.1.2.
+
+```sh
+pnpm add @kutur-kit/assets@alpha effect
+```
+
+## Assets
+
+A bucket is a service. Its id names it in errors; the physical bucket is chosen by the Layer that provides it:
+
+```ts
+import { Asset, AssetBucket } from "@kutur-kit/assets";
+
+export class Avatars extends AssetBucket.Service<Avatars>()("avatars") {}
+
+export const Avatar = Asset.make("avatar", {
+  bucket: Avatars,
+  key: AvatarId,
+  contentTypes: ["image/png", "image/jpeg", "image/webp"],
+  maxSize: "2 MiB",
+  cacheControl: "public, max-age=31536000, immutable",
+});
+```
+
+| Option         | Meaning                                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------------------- |
+| `bucket`       | The bucket service.                                                                                       |
+| `key`          | A schema from the keys callers pass, such as a branded id, to a string. `Asset.Key` by default.           |
+| `contentTypes` | Accepted media types, lowercase and without parameters. Required: there is no default.                    |
+| `maxSize`      | A number of bytes or a string such as `"50 MiB"`.                                                         |
+| `cacheControl` | The `Cache-Control` objects are stored and served with. `no-cache` by default. CDN rules can override it. |
+
+Objects are stored under `<id>/<key>`, so several assets can share a bucket. Keys are checked before any request. Each segment uses S3's safe characters (letters, digits and `! - _ . ' ( )`), is not `.` or `..` and has at most 255 characters. A key has at most 1024 characters.
+
+```ts
+const program = Effect.gen(function* () {
+  const info = yield* Avatar.put(avatarId, body, { contentType: "image/png", contentLength });
+  const object = yield* Avatar.get(avatarId); // Option of { info, body }
+
+  yield* Avatar.delete(avatarId);
+});
+```
+
+`put` streams the body and fails with `Asset.TooLarge` as soon as it exceeds `maxSize`, with `Asset.ContentLengthMismatch` when it differs from the declared length and with `Asset.UnsupportedContentType` before reading it. A failed body leaves the previous object in place. `Asset.ContentType` and `Asset.Key` decode untrusted request values, such as headers and path parameters, to the types the asset accepts.
+
+`get` and `head` fail with `Asset.UnexpectedContentType` for an object the asset does not accept, such as one written by other code.
+
+## Storage
+
+| Module                         | Backs a bucket with                                             |
+| ------------------------------ | --------------------------------------------------------------- |
+| `@kutur-kit/assets/memory`     | Memory, for tests.                                              |
+| `@kutur-kit/assets/filesystem` | Files in a directory, for development.                          |
+| `@kutur-kit/assets/s3`         | S3 or a store with its API, such as R2 or RustFS.               |
+| `@kutur-kit/assets/alchemy/r2` | An R2 bucket declared with alchemy, through its Worker binding. |
+
+```ts
+import * as S3Assets from "@kutur-kit/assets/s3";
+
+export const AvatarsLive = S3Assets.layer(Avatars, { bucket: "avatars" });
+```
+
+The S3 layer needs `Credentials` and an `HttpClient` from `@distilled.cloud/aws`, and an `Endpoint` for stores other than AWS. For R2, `S3Assets.r2Endpoint(accountId)` gives the endpoint; sign requests for the region `auto`.
+
+## Signed uploads and downloads
+
+Large files go from the client to storage directly. `AssetSigning.Upload(asset)` decodes what a client declares, and `presignPut` signs a URL for exactly that:
+
+```ts
+import * as AssetSigning from "@kutur-kit/assets/AssetSigning";
+
+const NewFile = Schema.Struct({ ...AssetSigning.Upload(ProjectFile).fields, name: Schema.String });
+
+const start = (upload: typeof NewFile.Type) =>
+  Effect.gen(function* () {
+    // A `SignedRequest`: the client sends its method, URL and headers as given.
+    return yield* AssetSigning.presignPut(ProjectFile, fileId, upload, { expiresIn: "15 minutes" });
+  });
+
+const complete = (upload: typeof NewFile.Type) =>
+  Effect.gen(function* () {
+    // Fails with `AssetSigning.UploadNotConfirmed` unless the object arrived as declared.
+    yield* AssetSigning.confirm(ProjectFile, fileId, upload);
+  });
+```
+
+A signed upload is bound to its key, content type, length and the asset's cache control, and creates an object only: storage refuses a different request, and refuses the URL once the object exists. Confirm before recording an upload as complete, since the client may never send it.
+
+`presignGet` signs a download URL. Signing is a service per bucket:
+
+| Module                            | Signs                                                                |
+| --------------------------------- | -------------------------------------------------------------------- |
+| `S3Assets.signing`                | With SigV4, for S3-compatible storage.                               |
+| `@kutur-kit/assets/alchemy/r2`    | With the S3 credentials alchemy binds to a Worker for an R2 bucket.  |
+| `@kutur-kit/assets/signing/local` | With an HMAC, verified by its own routes, for development and tests. |
+
+Browsers send a CORS preflight before a signed upload. Allow `AssetSigning.uploadHeaders` for `PUT` from your app's origin in the bucket's CORS rules; `AssetsR2.corsRule(origins)` builds that rule for alchemy.
+
+## Public delivery
+
+`AssetDelivery.layer(bucket, { baseUrl })` maps keys to URLs under a CDN or public domain, and `AssetDelivery.url(asset, key)` returns one. `@kutur-kit/assets/delivery/local` serves a bucket from your app's server, as a public bucket would be served, with the stored cache control, `nosniff` and a sandboxing content security policy.
+
+Give an object a new key when its content changes, such as a new id per upload, so it can be cached with `immutable`.
+
+## R2 with alchemy
+
+```ts
+import * as Cloudflare from "@alchemy.run/cloudflare";
+import * as AssetsR2 from "@kutur-kit/assets/alchemy/r2";
+
+const Uploads = Cloudflare.R2.Bucket("Uploads", {
+  cors: [AssetsR2.corsRule(["https://app.example.com"])],
+});
+
+export default class Api extends Cloudflare.Worker<Api>()(
+  "Api",
+  { main: import.meta.url },
+  Effect.gen(function* () {
+    // ...
+  }).pipe(
+    Effect.provide(
+      Layer.mergeAll(AssetsR2.layer(Avatars, Uploads), AssetsR2.signing(Avatars, Uploads)).pipe(
+        Layer.provideMerge(Cloudflare.R2.ReadWriteBucketBinding),
+      ),
+    ),
+  ),
+) {}
+```
+
+`layer` stores through alchemy's `ReadWriteBucket`: provide `ReadWriteBucketBinding` in a Worker or `ReadWriteBucketHttp` elsewhere. Content type and cache control are stored as the object's HTTP metadata.
+
+## Testing
+
+`@kutur-kit/assets/testing` has contracts for other implementations: `AssetBucketContract.cases` for a bucket and `AssetSigningContract.cases` for signing and the storage it signs for. Each case is an Effect; run it with any test runner:
+
+```ts
+import * as Memory from "@kutur-kit/assets/memory";
+import { AssetBucketContract } from "@kutur-kit/assets/testing";
+
+for (const { name, run } of AssetBucketContract.cases)
+  it.effect(name, () => run.pipe(Effect.provide(Memory.layer(AssetBucketContract.ContractBucket))));
+```
+
+## Requirements
+
+- `effect` 4.1.2 or later 4.x.
+- `@kutur-kit/assets/s3` needs `@distilled.cloud/aws` 1.0.0-rc.18.
+- `@kutur-kit/assets/alchemy/r2` needs `alchemy` and `@alchemy.run/cloudflare` 2.0.0-beta.85.
+
+## Limitations
+
+- The S3 and R2 layers collect a body before sending it, so uploads through the app are limited by memory. Larger files belong in signed uploads.
+- `alchemy/r2` works only in code bundled by alchemy: its modules import packages that other bundlers, such as Wrangler's, cannot resolve. Its bucket operations fail if called while a Worker is constructed rather than while it handles a request.
+- `AssetsR2.signing` deploys a bucket-scoped API token for the Worker, which needs a Cloudflare API token with the account permission API Tokens Write. OAuth sessions cannot create one.
+- Signed URLs work until they expire, whoever holds them. Removing a user's access does not revoke URLs already handed out.
+- `signing/local` checks that an object does not exist before writing it, so two uploads racing to one key may both succeed.
+- The filesystem layer is atomic for one process only.
+- A changed `cacheControl` applies to new objects; stored objects keep theirs.

package/dist/Asset.d.ts

@@ -0,0 +1,174 @@
+import type * as AssetBucket from "./AssetBucket.ts";
+import { ByteSize, Effect, Option, Schema, Stream } from "effect";
+/**
+ * A media type without parameters, such as `image/png`. Only the top-level
+ * type is checked, which catches typos without a registry of every subtype.
+ */
+export type MediaType = `${"application" | "audio" | "font" | "image" | "model" | "text" | "video"}/${string}`;
+/**
+ * A key that fits every store and URL without encoding: segments separated by
+ * `/`, each made of letters, digits and `! - _ . ' ( )`, not `.` or `..`, at
+ * most 255 characters each and 1024 in all. The asset id prefix also counts towards the limit,
+ * which each asset's `Key` checks.
+ */
+export declare const Key: Schema.brand<Schema.String, "@kutur-kit/assets/Key">;
+export type Key = typeof Key.Type;
+/** Encodes an asset's keys to strings. Its encoded keys are checked like `Key`. */
+export type KeySchema<K> = Schema.Codec<K, string>;
+export interface Definition<Type extends MediaType = MediaType, K = Key> {
+    /** A bucket from `AssetBucket.Service`. */
+    readonly bucket: AssetBucket.Any;
+    /**
+     * The keys callers pass, such as a `UserId` or a `Schema.TemplateLiteral`
+     * of ids. `Key` by default.
+     */
+    readonly key?: KeySchema<K>;
+    /**
+     * Accepted media types, in lowercase and without parameters. There is no
+     * default: a bucket served from your domain must not accept arbitrary types
+     * such as `text/html`.
+     */
+    readonly contentTypes: readonly [Type, ...ReadonlyArray<Type>];
+    /**
+     * Such as `"5 MiB"` or a number of bytes. Checked while the body streams,
+     * before the store commits it.
+     */
+    readonly maxSize: ByteSize.Input;
+    /**
+     * The `Cache-Control` objects are stored and served with, such as
+     * `public, max-age=31536000, immutable` when each upload gets a new key.
+     * Public buckets, such as R2's on a custom domain, send it to CDNs and
+     * browsers.
+     *
+     * `no-cache` by default. Without one, a CDN applies its own default TTL,
+     * and browsers send `no-cache` with signed uploads anyway: they add it to
+     * requests with `If-None-Match`, which makes those write-once.
+     *
+     * CDN rules can override it, such as Cloudflare Cache Rules set to
+     * override origin or a CloudFront minimum TTL. Changing it here applies to
+     * new objects only: stored ones keep theirs.
+     */
+    readonly cacheControl?: string | undefined;
+}
+/** The keys an asset definition takes: its key schema's type, or `Key`. */
+export type KeyOf<D> = D extends {
+    readonly key: KeySchema<infer K>;
+} ? K : Key;
+export type ContentTypeOf<D extends Definition<MediaType, unknown>> = D["contentTypes"][number];
+/** An id that is one key segment, or a message naming the problem. */
+export type CheckId<Id extends string> = Id extends "" | "." | ".." | `${string}/${string}` ? "Asset ids must be one key segment, without `/` and not `.` or `..`" : Id;
+/** A content type in lowercase without parameters, or a message naming the problem. */
+export type CheckContentType<Type extends string> = Type extends `${string};${string}` | `${string} ${string}` ? "Asset content types must have no parameters, such as `; charset=utf-8`" : Type extends `${string}${UppercaseLetter}${string}` ? "Asset content types must be lowercase" : Type;
+type UppercaseLetter = Uppercase<"a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z">;
+declare const InvalidKey_base: Schema.Class<InvalidKey, Schema.TaggedStruct<"AssetInvalidKey", {
+    readonly asset: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+export declare class InvalidKey extends InvalidKey_base {
+}
+declare const UnsupportedContentType_base: Schema.Class<UnsupportedContentType, Schema.TaggedStruct<"AssetUnsupportedContentType", {
+    readonly asset: Schema.String;
+    readonly contentType: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+export declare class UnsupportedContentType extends UnsupportedContentType_base {
+}
+declare const ContentLengthMismatch_base: Schema.Class<ContentLengthMismatch, Schema.TaggedStruct<"AssetContentLengthMismatch", {
+    readonly asset: Schema.String;
+    readonly contentLength: Schema.ByteSize;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/** A body is longer or shorter than the `contentLength` declared for it. */
+export declare class ContentLengthMismatch extends ContentLengthMismatch_base {
+}
+declare const TooLarge_base: Schema.Class<TooLarge, Schema.TaggedStruct<"AssetTooLarge", {
+    readonly asset: Schema.String;
+    readonly maxSize: Schema.ByteSize;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+export declare class TooLarge extends TooLarge_base {
+}
+declare const UnexpectedContentType_base: Schema.Class<UnexpectedContentType, Schema.TaggedStruct<"AssetUnexpectedContentType", {
+    readonly asset: Schema.String;
+    /** The key in the store, with the asset id prefix. */
+    readonly key: Schema.String;
+    readonly contentType: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * A stored object's content type is not one the asset accepts, such as one
+ * written by other code or under an older definition.
+ */
+export declare class UnexpectedContentType extends UnexpectedContentType_base {
+}
+export interface Info<Type extends MediaType> extends AssetBucket.Info {
+    readonly contentType: Type;
+}
+export interface StoredObject<Type extends MediaType> extends AssetBucket.StoredObject {
+    readonly info: Info<Type>;
+}
+export type ReadError = InvalidKey | UnexpectedContentType | AssetBucket.AssetBucketError;
+/** What `toLayer` helpers need of an asset. */
+export interface Any {
+    readonly id: string;
+    readonly bucket: AssetBucket.Any;
+}
+/** The bucket service an asset requires. */
+export type BucketOf<A> = A extends {
+    readonly bucket: AssetBucket.Tag<infer B>;
+} ? B : never;
+export interface Asset<Id extends string, Type extends MediaType, K, B> {
+    readonly id: Id;
+    readonly bucket: AssetBucket.Tag<B>;
+    readonly contentTypes: ReadonlyArray<Type>;
+    readonly maxSize: ByteSize.ByteSize;
+    readonly cacheControl: string;
+    /**
+     * Decodes an untrusted key, such as a path parameter, to one the asset
+     * accepts, checking that the stored key is portable.
+     */
+    readonly Key: KeySchema<K>;
+    /**
+     * Decodes an untrusted content type, such as a request header, to one the
+     * asset accepts. Ignores case, whitespace and parameters such as `charset`.
+     */
+    readonly ContentType: Schema.Codec<Type, string>;
+    readonly put: <E>(key: K, body: Stream.Stream<Uint8Array, E>, options: {
+        readonly contentType: Type;
+        /**
+         * The body's length, such as a request's `Content-Length`. A length
+         * over `maxSize` fails before the body is read, and the bucket can
+         * stream a body of known length.
+         */
+        readonly contentLength?: ByteSize.ByteSize | undefined;
+    }) => Effect.Effect<Info<Type>, InvalidKey | UnsupportedContentType | TooLarge | ContentLengthMismatch | AssetBucket.AssetBucketError | E, B>;
+    readonly get: (key: K) => Effect.Effect<Option.Option<StoredObject<Type>>, ReadError, B>;
+    readonly head: (key: K) => Effect.Effect<Option.Option<Info<Type>>, ReadError, B>;
+    readonly delete: (key: K) => Effect.Effect<void, InvalidKey | AssetBucket.AssetBucketError, B>;
+    /** The key the object is stored under in the bucket: `<id>/<encoded key>`, checked. */
+    readonly storedKey: (key: K) => Effect.Effect<string, InvalidKey>;
+    /**
+     * Checks a content type and length as `put` does, for uploads that do not
+     * pass through `put`, such as to presigned URLs.
+     */
+    readonly check: (upload: {
+        readonly contentType: Type;
+        readonly contentLength: ByteSize.ByteSize;
+    }) => Effect.Effect<void, UnsupportedContentType | TooLarge>;
+}
+/**
+ * Defines a kind of asset. Objects are stored in the definition's bucket
+ * under `<id>/<key>`, so several kinds can share a bucket.
+ */
+export declare const make: <const Id extends string, const D extends Definition<MediaType, unknown>, B>(checkedId: CheckId<Id>, definition: D & {
+    readonly bucket: AssetBucket.Tag<B>;
+    readonly contentTypes: ReadonlyArray<CheckContentType<ContentTypeOf<D>>>;
+}) => Asset<Id, ContentTypeOf<D>, KeyOf<D>, B>;
+export {};
+//# sourceMappingURL=Asset.d.ts.map

package/dist/Asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Asset.d.ts","sources":["../src/Asset.ts"],"names":[],"mappings":"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"}

package/dist/Asset.js

@@ -0,0 +1,156 @@
+import { ByteSize, Effect, Option, Schema, SchemaGetter, Stream } from "effect";
+// S3 and R2 limit keys to 1024 bytes, prefixes included. Keys are ASCII, so
+// bytes are characters.
+// https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html
+// https://developers.cloudflare.com/r2/platform/limits/
+const maxKeyLength = 1024;
+// S3's safe characters, without `*`, which Windows file names forbid. Keys made
+// of these need no encoding in URLs or file system paths. S3 also advises
+// against `.` and `..` segments, which tools resolve as relative paths.
+// https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines
+// https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+const segmentPattern = /^[0-9A-Za-z!\-_.'()]+$/;
+// Stores that keep objects as files, such as RustFS, refuse longer segments,
+// as file systems limit names to 255 bytes.
+const maxSegmentLength = 255;
+const isSegment = (segment) => segmentPattern.test(segment) &&
+    segment.length <= maxSegmentLength &&
+    segment !== "." &&
+    segment !== "..";
+const portable = (prefix) => Schema.makeFilter((key) => {
+    if (!key.split("/").every(isSegment))
+        return "segments must be non-empty, not `.` or `..`, at most 255 characters, and use only letters, digits and ! - _ . ' ( )";
+    if (prefix.length + key.length > maxKeyLength)
+        return `${prefix === "" ? "keys" : `keys with the prefix ${prefix}`} must fit in ${maxKeyLength} characters`;
+    return undefined;
+});
+/**
+ * A key that fits every store and URL without encoding: segments separated by
+ * `/`, each made of letters, digits and `! - _ . ' ( )`, not `.` or `..`, at
+ * most 255 characters each and 1024 in all. The asset id prefix also counts towards the limit,
+ * which each asset's `Key` checks.
+ */
+export const Key = Schema.String.check(portable("")).pipe(Schema.brand("@kutur-kit/assets/Key"));
+export class InvalidKey extends Schema.TaggedError()("AssetInvalidKey", { asset: Schema.String, reason: Schema.String }, { httpApiStatus: 400 }) {
+}
+export class UnsupportedContentType extends Schema.TaggedError()("AssetUnsupportedContentType", { asset: Schema.String, contentType: Schema.String }, { httpApiStatus: 415 }) {
+}
+/** A body is longer or shorter than the `contentLength` declared for it. */
+export class ContentLengthMismatch extends Schema.TaggedError()("AssetContentLengthMismatch", { asset: Schema.String, contentLength: Schema.ByteSize }, { httpApiStatus: 400 }) {
+}
+export class TooLarge extends Schema.TaggedError()("AssetTooLarge", { asset: Schema.String, maxSize: Schema.ByteSize }, { httpApiStatus: 413 }) {
+}
+/**
+ * A stored object's content type is not one the asset accepts, such as one
+ * written by other code or under an older definition.
+ */
+export class UnexpectedContentType extends Schema.TaggedError()("AssetUnexpectedContentType", {
+    asset: Schema.String,
+    /** The key in the store, with the asset id prefix. */
+    key: Schema.String,
+    contentType: Schema.String,
+}) {
+}
+const essence = (contentType) => contentType.replace(/;.*/su, "").trim().toLowerCase();
+/**
+ * Defines a kind of asset. Objects are stored in the definition's bucket
+ * under `<id>/<key>`, so several kinds can share a bucket.
+ */
+export const make = (checkedId, definition) => {
+    // SAFETY: CheckId<Id> is Id itself for every id the check below accepts.
+    const id = checkedId;
+    if (!isSegment(id))
+        throw new Error(`Asset id must be a single key segment: ${JSON.stringify(id)}`);
+    const maxSize = Option.getOrThrowWith(ByteSize.fromInput(definition.maxSize), () => new Error(`Asset ${id} maxSize is not a byte size: ${String(definition.maxSize)}`));
+    for (const contentType of definition.contentTypes)
+        if (essence(contentType) !== contentType)
+            throw new Error(`Asset ${id} content types must be lowercase without parameters: ${JSON.stringify(contentType)}`);
+    const cacheControl = definition.cacheControl ?? "no-cache";
+    const accepted = new Set(definition.contentTypes);
+    const isAccepted = (contentType) => accepted.has(contentType);
+    const ContentType = Schema.String.pipe(Schema.decodeTo(Schema.String, {
+        decode: SchemaGetter.transform(essence),
+        encode: SchemaGetter.passthrough(),
+    }), Schema.decodeTo(Schema.Literals(definition.contentTypes)));
+    // SAFETY: KeyOf<D> is the type of the definition's key schema, or Key without one.
+    const keySchema = (definition.key ?? Key);
+    const AssetKey = Schema.String.check(portable(`${id}/`)).pipe(Schema.decodeTo(keySchema));
+    const encodeKey = Schema.encodeEffect(AssetKey);
+    const locate = (key) => encodeKey(key).pipe(Effect.mapError((error) => new InvalidKey({ asset: id, reason: error.message })), Effect.map((encoded) => `${id}/${encoded}`));
+    // Types can be bypassed, so `put` checks again what the compiler checked.
+    const accept = (contentType) => isAccepted(contentType)
+        ? Effect.void
+        : Effect.fail(new UnsupportedContentType({ asset: id, contentType }));
+    const expect = (key, info) => isAccepted(info.contentType)
+        ? Effect.succeed({ ...info, contentType: info.contentType })
+        : Effect.fail(new UnexpectedContentType({ asset: id, key, contentType: info.contentType }));
+    const declared = (contentLength) => contentLength !== undefined && contentLength > maxSize
+        ? Effect.fail(new TooLarge({ asset: id, maxSize }))
+        : Effect.void;
+    // Fails a body over maxSize or its declared length as soon as it is, and
+    // one shorter than its declared length at its end, before the bucket commits.
+    const measure = (body, contentLength) => Stream.suspend(() => {
+        let size = 0n;
+        const check = (chunk) => {
+            size += BigInt(chunk.length);
+            if (size > maxSize)
+                return Effect.fail(new TooLarge({ asset: id, maxSize }));
+            return contentLength !== undefined && size > contentLength
+                ? Effect.fail(new ContentLengthMismatch({ asset: id, contentLength }))
+                : Effect.succeed(chunk);
+        };
+        const counted = Stream.mapEffect(body, check);
+        if (contentLength === undefined)
+            return counted;
+        const complete = Effect.suspend(() => size === contentLength
+            ? Effect.void
+            : Effect.fail(new ContentLengthMismatch({ asset: id, contentLength })));
+        return Stream.concat(counted, Stream.fromEffectDrain(complete));
+    });
+    return {
+        id,
+        bucket: definition.bucket,
+        contentTypes: definition.contentTypes,
+        maxSize,
+        cacheControl,
+        Key: AssetKey,
+        ContentType,
+        put: (key, body, { contentType, contentLength }) => Effect.gen(function* () {
+            const stored = yield* locate(key);
+            yield* accept(contentType);
+            yield* declared(contentLength);
+            const bucket = yield* definition.bucket;
+            const info = yield* bucket.put({
+                key: stored,
+                contentType,
+                cacheControl,
+                body: measure(body, contentLength),
+                contentLength,
+            });
+            return { ...info, contentType };
+        }),
+        get: (key) => Effect.gen(function* () {
+            const stored = yield* locate(key);
+            const bucket = yield* definition.bucket;
+            const object = yield* bucket.get(stored);
+            if (Option.isNone(object))
+                return Option.none();
+            const info = yield* expect(stored, object.value.info);
+            return Option.some({ ...object.value, info });
+        }),
+        head: (key) => Effect.gen(function* () {
+            const stored = yield* locate(key);
+            const bucket = yield* definition.bucket;
+            const info = yield* bucket.head(stored);
+            return Option.isNone(info) ? Option.none() : Option.some(yield* expect(stored, info.value));
+        }),
+        delete: (key) => Effect.gen(function* () {
+            const stored = yield* locate(key);
+            const bucket = yield* definition.bucket;
+            yield* bucket.delete(stored);
+        }),
+        storedKey: locate,
+        check: ({ contentType, contentLength }) => Effect.andThen(accept(contentType), declared(contentLength)),
+    };
+};
+//# sourceMappingURL=Asset.js.map

package/dist/Asset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Asset.js","sources":["../src/Asset.ts"],"names":[],"mappings":"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"}

package/dist/AssetBucket.d.ts

@@ -0,0 +1,73 @@
+import { type ByteSize, Context, type Effect, type Option, Schema, type Stream } from "effect";
+export interface Info {
+    readonly size: ByteSize.ByteSize;
+    readonly contentType: string;
+    /**
+     * The `Cache-Control` the object is served with, such as by a CDN in front
+     * of a public bucket. Absent when the object has none.
+     */
+    readonly cacheControl?: string | undefined;
+}
+export interface StoredObject {
+    readonly info: Info;
+    /** Implementations may stream from storage, so read it at most once. */
+    readonly body: Stream.Stream<Uint8Array, AssetBucketError>;
+}
+export interface PutInput<E> {
+    readonly key: string;
+    readonly contentType: string;
+    /** Stored with the object, to be served with it. */
+    readonly cacheControl?: string | undefined;
+    readonly body: Stream.Stream<Uint8Array, E>;
+    /**
+     * The body's exact length, when the caller knows it. Stores that need a
+     * length to stream, such as R2, would otherwise buffer the body.
+     */
+    readonly contentLength?: ByteSize.ByteSize | undefined;
+}
+declare const AssetBucketError_base: Schema.Class<AssetBucketError, Schema.TaggedStruct<"AssetBucketError", {
+    readonly operation: Schema.Literals<readonly ["put", "get", "head", "delete", "sign"]>;
+    readonly bucket: Schema.String;
+    readonly key: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+export declare class AssetBucketError extends AssetBucketError_base {
+}
+/**
+ * Object storage for one bucket. Implementations must keep keys apart,
+ * including a key and the keys nested under it, replace an object on `put`,
+ * keep its content type and cache control,
+ * leave the previous object in place when a body fails and treat deleting a
+ * missing object as success.
+ */
+export interface Bucket {
+    readonly put: <E>(input: PutInput<E>) => Effect.Effect<Info, AssetBucketError | E>;
+    readonly get: (key: string) => Effect.Effect<Option.Option<StoredObject>, AssetBucketError>;
+    readonly head: (key: string) => Effect.Effect<Option.Option<Info>, AssetBucketError>;
+    readonly delete: (key: string) => Effect.Effect<void, AssetBucketError>;
+}
+/** A logical bucket: assets name it, and a layer per environment backs it. */
+export interface Tag<Self, Id extends string = string> extends Context.Service<Self, Bucket> {
+    new (_: never): {
+        readonly key: `@kutur-kit/assets/AssetBucket/${Id}`;
+    };
+    readonly id: Id;
+}
+/** What asset definitions need of a bucket. Its `Tag` adds the service type. */
+export interface Any {
+    readonly id: string;
+}
+/**
+ * Declares a logical bucket as a service:
+ *
+ * ```ts
+ * export class Public extends AssetBucket.Service<Public>()("public") {}
+ * ```
+ *
+ * The id names the bucket in errors and adapters; it is not a physical bucket name.
+ */
+export declare const Service: <Self>() => <const Id extends string>(id: Id) => Tag<Self, Id>;
+export {};
+//# sourceMappingURL=AssetBucket.d.ts.map

package/dist/AssetBucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetBucket.d.ts","sources":["../src/AssetBucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE/F,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC;CACxD;;;;;;;oBAImB,OAAO,MAAM;;AAFjC,qBAAa,gBAAiB,SAAQ,qBAQpC;CAAG;AAEL;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,CAAC,CAAC,CAAC;IACnF,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC5F,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;CACzE;AAED,8EAA8E;AAC9E,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;IAI1F,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,iCAAiC,EAAE,EAAE,CAAA;KAAE,CAAC;IACxE,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GACjB,IAAI,QACJ,KAAK,CAAC,EAAE,SAAS,MAAM,MAAM,EAAE,KAAG,GAAG,CAAC,IAAI,EAAE,EAAE,CACgD,CAAC"}

package/dist/AssetBucket.js

@@ -0,0 +1,19 @@
+import { Context, Schema } from "effect";
+export class AssetBucketError extends Schema.TaggedError()("AssetBucketError", {
+    operation: Schema.Literals(["put", "get", "head", "delete", "sign"]),
+    bucket: Schema.String,
+    key: Schema.String,
+    cause: Schema.Defect(),
+}) {
+}
+/**
+ * Declares a logical bucket as a service:
+ *
+ * ```ts
+ * export class Public extends AssetBucket.Service<Public>()("public") {}
+ * ```
+ *
+ * The id names the bucket in errors and adapters; it is not a physical bucket name.
+ */
+export const Service = () => (id) => Object.assign(Context.Service()(`@kutur-kit/assets/AssetBucket/${id}`), { id });
+//# sourceMappingURL=AssetBucket.js.map

package/dist/AssetBucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetBucket.js","sources":["../src/AssetBucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,OAAO,EAA4B,MAAM,EAAe,MAAM,QAAQ,CAAC;AA+B/F,MAAM,OAAO,gBAAiB,SAAQ,MAAM,CAAC,WAAW,EAGrD,CAAC,kBAAkB,EAAE;IACtB,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC,MAAM;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;CACvB,CAAC;CAAG;AA8BL;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAClB,GAAS,EAAE,CACX,CAA0B,EAAM,EAAiB,EAAE,CACjD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAgB,CAAC,iCAAiC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC"}