lean-s3 0.2.2 → 0.3.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -19,15 +19,14 @@
   "types": "./dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "build": "tsgo",
-    "clean": "rimraf dist",
+    "build": "tsup",
     "test": "tsgo && node --test dist/*.test.js",
     "test:integration": "tsgo && node --test dist/test.integration.js",
     "ci": "biome ci ./src",
     "docs": "typedoc",
     "lint": "biome lint ./src",
     "format": "biome format --write ./src && biome lint --write ./src && biome check --write ./src",
-    "prepublishOnly": "npm run clean && npm run build"
+    "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
@@ -37,9 +36,8 @@
     "@typescript/native-preview": "^7.0.0-dev.20250613.1",
     "expect": "^30.0.0",
     "lefthook": "^1.11.13",
-    "rimraf": "^6.0.1",
-    "typedoc": "^0.28.5",
-    "typescript": "^5.8.3"
+    "tsup": "^8.5.0",
+    "typedoc": "^0.28.5"
   },
   "engines": {
     "node": "^20.19.0 || ^22.14.0 || ^24.0.0"

package/dist/AmzDate.d.ts

@@ -1,7 +0,0 @@
-export type AmzDate = {
-    numericDayStart: number;
-    date: string;
-    dateTime: string;
-};
-export declare function getAmzDate(dateTime: Date): AmzDate;
-export declare function now(): AmzDate;

package/dist/AmzDate.js

@@ -1,29 +0,0 @@
-const ONE_DAY = 1000 * 60 * 60 * 24;
-export function getAmzDate(dateTime) {
-    const date = pad4(dateTime.getUTCFullYear()) +
-        pad2(dateTime.getUTCMonth() + 1) +
-        pad2(dateTime.getUTCDate());
-    const time = pad2(dateTime.getUTCHours()) +
-        pad2(dateTime.getUTCMinutes()) +
-        pad2(dateTime.getUTCSeconds()); // it seems that we dont support milliseconds
-    return {
-        numericDayStart: (dateTime.getTime() / ONE_DAY) | 0,
-        date,
-        dateTime: `${date}T${time}Z`,
-    };
-}
-export function now() {
-    return getAmzDate(new Date());
-}
-function pad4(v) {
-    return v < 10
-        ? `000${v}`
-        : v < 100
-            ? `00${v}`
-            : v < 1000
-                ? `0${v}`
-                : v.toString();
-}
-function pad2(v) {
-    return v < 10 ? `0${v}` : v.toString();
-}

package/dist/KeyCache.d.ts

@@ -1,5 +0,0 @@
-import type { AmzDate } from "./AmzDate.ts";
-export default class KeyCache {
-    #private;
-    computeIfAbsent(date: AmzDate, region: string, accessKeyId: string, secretAccessKey: string): Buffer;
-}

package/dist/KeyCache.js

@@ -1,21 +0,0 @@
-import * as sign from "./sign.js";
-export default class KeyCache {
-    #lastNumericDay = -1;
-    #keys = new Map();
-    computeIfAbsent(date, region, accessKeyId, secretAccessKey) {
-        if (date.numericDayStart !== this.#lastNumericDay) {
-            this.#keys.clear();
-            this.#lastNumericDay = date.numericDayStart;
-            // TODO: Add mechanism to clear the cache after some time
-        }
-        // using accessKeyId to prevent keeping the secretAccessKey somewhere
-        const cacheKey = `${date.date}:${region}:${accessKeyId}`;
-        const key = this.#keys.get(cacheKey);
-        if (key) {
-            return key;
-        }
-        const newKey = sign.deriveSigningKey(date.date, region, secretAccessKey);
-        this.#keys.set(cacheKey, newKey);
-        return newKey;
-    }
-}

package/dist/S3BucketEntry.d.ts

@@ -1,19 +0,0 @@
-import type { ChecksumType, ChecksumAlgorithm, StorageClass } from "./index.ts";
-/**
- * @internal Normally, we'd use an interface for that, but having a class with pre-defined fields makes it easier for V8 top optimize hidden classes.
- */
-export default class S3BucketEntry {
-    readonly key: string;
-    readonly size: number;
-    readonly lastModified: Date;
-    readonly etag: string;
-    readonly storageClass: StorageClass;
-    readonly checksumAlgorithm: ChecksumAlgorithm | undefined;
-    readonly checksumType: ChecksumType | undefined;
-    constructor(key: string, size: number, lastModified: Date, etag: string, storageClass: StorageClass, checksumAlgorithm: ChecksumAlgorithm | undefined, checksumType: ChecksumType | undefined);
-    /**
-     * @internal
-     */
-    // biome-ignore lint/suspicious/noExplicitAny: internal use only, any is ok here
-    static parse(source: any): S3BucketEntry;
-}

package/dist/S3BucketEntry.js

@@ -1,29 +0,0 @@
-/**
- * @internal Normally, we'd use an interface for that, but having a class with pre-defined fields makes it easier for V8 top optimize hidden classes.
- */
-export default class S3BucketEntry {
-    key;
-    size;
-    lastModified;
-    etag;
-    storageClass;
-    checksumAlgorithm;
-    checksumType;
-    constructor(key, size, lastModified, etag, storageClass, checksumAlgorithm, checksumType) {
-        this.key = key;
-        this.size = size;
-        this.lastModified = lastModified;
-        this.etag = etag;
-        this.storageClass = storageClass;
-        this.checksumAlgorithm = checksumAlgorithm;
-        this.checksumType = checksumType;
-    }
-    /**
-     * @internal
-     */
-    // biome-ignore lint/suspicious/noExplicitAny: internal use only, any is ok here
-    static parse(source) {
-        // TODO: check values and throw exceptions
-        return new S3BucketEntry(source.Key, source.Size, new Date(source.LastModified), source.ETag, source.StorageClass, source.ChecksumAlgorithm, source.ChecksumType);
-    }
-}

package/dist/S3Client.d.ts

@@ -1,210 +0,0 @@
-import { type Dispatcher } from "undici";
-import S3File from "./S3File.ts";
-import S3BucketEntry from "./S3BucketEntry.ts";
-import * as amzDate from "./AmzDate.ts";
-import type { Acl, BucketInfo, BucketLocationInfo, HttpMethod, PresignableHttpMethod, StorageClass, UndiciBodyInit } from "./index.ts";
-export declare const write: unique symbol;
-export declare const stream: unique symbol;
-export interface S3ClientOptions {
-    bucket: string;
-    region: string;
-    endpoint: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken?: string;
-}
-export type OverridableS3ClientOptions = Pick<S3ClientOptions, "region" | "bucket" | "endpoint">;
-// biome-ignore lint/complexity/noBannedTypes: TODO
-export type CreateFileInstanceOptions = {}; // TODO
-export type DeleteObjectsOptions = {
-    signal?: AbortSignal;
-};
-export interface S3FilePresignOptions {
-    contentHash: Buffer;
-    /** Seconds. */
-    expiresIn: number; // TODO: Maybe support Temporal.Duration once major support arrives
-    method: PresignableHttpMethod;
-    storageClass: StorageClass;
-    acl: Acl;
-}
-export type ListObjectsOptions = {
-    bucket?: string;
-    prefix?: string;
-    maxKeys?: number;
-    startAfter?: string;
-    continuationToken?: string;
-    signal?: AbortSignal;
-};
-export type ListObjectsIteratingOptions = {
-    bucket?: string;
-    prefix?: string;
-    startAfter?: string;
-    signal?: AbortSignal;
-    internalPageSize?: number;
-};
-export type ListObjectsResponse = {
-    name: string;
-    prefix: string | undefined;
-    startAfter: string | undefined;
-    isTruncated: boolean;
-    continuationToken: string | undefined;
-    maxKeys: number;
-    keyCount: number;
-    nextContinuationToken: string | undefined;
-    contents: readonly S3BucketEntry[];
-};
-export type BucketCreationOptions = {
-    locationConstraint?: string;
-    location?: BucketLocationInfo;
-    info?: BucketInfo;
-    signal?: AbortSignal;
-};
-export type BucketDeletionOptions = {
-    signal?: AbortSignal;
-};
-export type BucketExistsOptions = {
-    signal?: AbortSignal;
-};
-/**
- * A configured S3 bucket instance for managing files.
- *
- * @example
- * ```js
- * // Basic bucket setup
- * const bucket = new S3Client({
- *   bucket: "my-bucket",
- *   accessKeyId: "key",
- *   secretAccessKey: "secret"
- * });
- * // Get file instance
- * const file = bucket.file("image.jpg");
- * await file.delete();
- * ```
- */
-export default class S3Client {
-    #private;
-    /**
-     * Create a new instance of an S3 bucket so that credentials can be managed from a single instance instead of being passed to every method.
-     *
-     * @param  options The default options to use for the S3 client.
-     */
-    constructor(options: S3ClientOptions);
-    /**
-     * Creates an S3File instance for the given path.
-     *
-     * @param {string} path The path to the object in the bucket. ALso known as [object key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html).
-     * We recommend not using the following characters in a key name because of significant special character handling, which isn't consistent across all applications (see [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html)):
-     * - Backslash (`\\`)
-     * - Left brace (`{`)
-     * - Non-printable ASCII characters (128–255 decimal characters)
-     * - Caret or circumflex (`^`)
-     * - Right brace (`}`)
-     * - Percent character (`%`)
-     * - Grave accent or backtick (`\``)
-     * - Right bracket (`]`)
-     * - Quotation mark (`"`)
-     * - Greater than sign (`>`)
-     * - Left bracket (`[`)
-     * - Tilde (`~`)
-     * - Less than sign (`<`)
-     * - Pound sign (`#`)
-     * - Vertical bar or pipe (`|`)
-     *
-     * lean-s3 does not enforce these restrictions.
-     *
-     * @param {Partial<CreateFileInstanceOptions>} [options] TODO
-     * @example
-     * ```js
-     * const file = client.file("image.jpg");
-     * await file.write(imageData);
-     *
-     * const configFile = client.file("config.json", {
-     *   type: "application/json",
-     *   acl: "private"
-     * });
-     * ```
-     */
-    file(path: string, options?: Partial<CreateFileInstanceOptions>): S3File;
-    /**
-     * Generate a presigned URL for temporary access to a file.
-     * Useful for generating upload/download URLs without exposing credentials.
-     * @returns The operation on {@link S3Client#presign.path} as a pre-signed URL.
-     *
-     * @example
-     * ```js
-     * const downloadUrl = client.presign("file.pdf", {
-     *   expiresIn: 3600 // 1 hour
-     * });
-     * ```
-     */
-    presign(path: string, { method, expiresIn, // TODO: Maybe rename this to expiresInSeconds
-    storageClass, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
-    /**
-     * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
-     */
-    deleteObjects(objects: readonly S3BucketEntry[] | readonly string[], options?: DeleteObjectsOptions): Promise<{
-        errors: {
-            code: any;
-            key: any;
-            message: any;
-            versionId: any;
-        }[];
-    } | null>;
-    /**
-     * Creates a new bucket on the S3 server.
-     *
-     * @param name The name of the bucket to create. AWS the name according to [some rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html). The most important ones are:
-     * - Bucket names must be between `3` (min) and `63` (max) characters long.
-     * - Bucket names can consist only of lowercase letters, numbers, periods (`.`), and hyphens (`-`).
-     * - Bucket names must begin and end with a letter or number.
-     * - Bucket names must not contain two adjacent periods.
-     * - Bucket names must not be formatted as an IP address (for example, `192.168.5.4`).
-     *
-     * @throws {Error} If the bucket name is invalid.
-     * @throws {S3Error} If the bucket could not be created, e.g. if it already exists.
-     * @remarks Uses [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
-     */
-    createBucket(name: string, options?: BucketCreationOptions): Promise<void>;
-    /**
-     * Deletes a bucket from the S3 server.
-     * @param name The name of the bucket to delete. Same restrictions as in {@link S3Client#createBucket}.
-     * @throws {Error} If the bucket name is invalid.
-     * @throws {S3Error} If the bucket could not be deleted, e.g. if it is not empty.
-     * @remarks Uses [`DeleteBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html).
-     */
-    deleteBucket(name: string, options?: BucketDeletionOptions): Promise<void>;
-    /**
-     * Checks if a bucket exists.
-     * @param name The name of the bucket to delete. Same restrictions as in {@link S3Client#createBucket}.
-     * @throws {Error} If the bucket name is invalid.
-     * @remarks Uses [`HeadBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html).
-     */
-    bucketExists(name: string, options?: BucketExistsOptions): Promise<boolean>;
-    //#region list
-    /**
-     * Uses [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys. Pagination and continuation is handled internally.
-     */
-    listIterating(options: ListObjectsIteratingOptions): AsyncGenerator<S3BucketEntry>;
-    /**
-     * Implements [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys.
-     */
-    list(options?: ListObjectsOptions): Promise<ListObjectsResponse>;
-    //#endregion
-    /**
-     * Do not use this. This is an internal method.
-     * TODO: Maybe move this into a separate free function?
-     * @internal
-     */
-    _signedRequest(method: HttpMethod, pathWithoutBucket: string, query: string | undefined, body: UndiciBodyInit | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, bucket: string | undefined, signal?: AbortSignal | undefined): Promise<Dispatcher.ResponseData<null>>;
-    /**
-     * @internal
-     * @param {import("./index.d.ts").UndiciBodyInit} data TODO
-     */
-    [write](path: string, data: UndiciBodyInit, contentType: string, contentLength: number | undefined, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined, signal?: AbortSignal | undefined): Promise<void>;
-    // TODO: Support abortSignal
-    /**
-     * @internal
-     */
-    [stream](path: string, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined): import("stream/web").ReadableStream<Uint8Array<ArrayBufferLike>>;
-}
-export declare function buildSearchParams(amzCredential: string, date: amzDate.AmzDate, expiresIn: number, headerList: string, contentHashStr: string | null | undefined, storageClass: StorageClass | null | undefined, sessionToken: string | null | undefined, acl: Acl | null | undefined): string;