lean-s3 0.1.6 → 0.2.1

package/README.md

@@ -77,7 +77,7 @@ $ du -sh node_modules
 `lean-s3` is _so_ lean that it is ~1.8MB just to do a couple of HTTP requests <img src="https://cdn.frankerfacez.com/emoticon/480839/1" width="20" height="20">
 BUT...
 
-Due to its scalability, portability and AWS integrations, pre-signing URLs is `async` and performs poorly in high-performance scenarios. By taking different trade-offs, lean-s3 can presign URLs much faster. I promise! This is the reason you cannot use lean-s3 in the browser.
+Due to the scalability, portability and AWS integrations of @aws-sdk/client-s3, pre-signing URLs is `async` and performs poorly in high-performance scenarios. By taking different trade-offs, lean-s3 can presign URLs much faster. I promise! This is the reason you cannot use lean-s3 in the browser.
 
 lean-s3 is currently about 30x faster than AWS SDK when it comes to pre-signing URLs[^1]:
 ```
@@ -121,6 +121,18 @@ We try to keep this library small. If you happen to need something that is not s
 
 See [DESIGN_DECISIONS.md](./DESIGN_DECISIONS.md) to read about why this library is the way it is.
 
+## Supported Operations
+
+### Bucket Operations
+- ✅ [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) via `.createBucket`
+
+### Object Operations
+- ✅ [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) via `.list`/`.listIterating`
+- ✅ [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) via `.deleteObjects`
+- ✅ [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) via `S3File.delete`
+- ✅ [`PutObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) via `S3File.write`
+- ✅ [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) via `S3File.exists`/`S3File.stat`
+
 ## Example Configurations
 ### Hetzner Object Storage
 ```js
@@ -159,4 +171,4 @@ const client = new S3Client({
 Popular S3 provider missing? Open an issue or file a PR!
 
 [^1]: Benchmark ran on a `13th Gen Intel(R) Core(TM) i7-1370P` using Node.js `23.11.0`. See `bench/` directory for the used benchmark.
-[^2]: `git clone git@github.com:nikeee/lean-s3.git && cd lean-s3 && npm ci && cd bench && npm ci && npm start`
+[^2]: `git clone git@github.com:nikeee/lean-s3.git && cd lean-s3 && npm ci && npm run build && cd bench && npm ci && npm start`

package/dist/AmzDate.d.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,18 @@
+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
+     */
+    static parse(source: any): S3BucketEntry;
+}

package/dist/S3BucketEntry.js

@@ -0,0 +1,29 @@
+/**
+ * @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

@@ -0,0 +1,175 @@
+import S3File from "./S3File.ts";
+import S3BucketEntry from "./S3BucketEntry.ts";
+import * as amzDate from "./AmzDate.ts";
+import type { Acl, BucketInfo, BucketLocationInfo, 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">;
+export type CreateFileInstanceOptions = {};
+export type DeleteObjectsOptions = {
+    signal?: AbortSignal;
+};
+export interface S3FilePresignOptions {
+    contentHash: Buffer;
+    /** Seconds. */
+    expiresIn: number;
+    method: PresignableHttpMethod;
+    storageClass: StorageClass;
+    acl: Acl;
+}
+export type ListObjectsOptions = {
+    prefix?: string;
+    maxKeys?: number;
+    startAfter?: string;
+    continuationToken?: string;
+    signal?: AbortSignal;
+};
+export type ListObjectsIteratingOptions = {
+    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;
+};
+/**
+ * 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.
+     * @remarks Uses [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
+     */
+    createBucket(name: string, options?: BucketCreationOptions): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * @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>;
+    /**
+     * @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;