@focus-at/zs3 0.0.0-stage → 0.0.4

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build Library and CLI
+        run: bun run build
+
+      - name: Publish Package
+        run: bun publish --access=public
+        env:
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Zimin
+
+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,49 @@
-# Temporary Holding Version
+# ZeroS3
+![GitHub License](https://img.shields.io/github/license/focus-at/zs3)
+![GitHub Stars](https://img.shields.io/github/stars/focus-at/zs3)
 
-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.
+An ultra-lightweight (~3 KB) and high-performance client for S3-compatible cloud storage (AWS S3, MinIO, Cloudflare R2, Backblaze B2), built purely on modern Web Standards (`fetch`, `crypto.subtle`).
+
+**Zero external dependencies.** Engineered for custom JS runtimes, Edge functions, Serverless environments, or any setup highly sensitive to bundle size and cold-start times.
+
+## Installation
+
+```js
+import { zs3 } from 'zeros3';
+```
+
+## Quick Start
+
+```js
+const storage = zs3({
+  endpoint: '127.0.0.1:9000',
+  accessKeyId: 'your-access-key-id',
+  secretAccessKey: 'your-secret-access-key',
+  bucket: 'production-assets'
+});
+
+// 1. Upload a file (String, Buffer, or Web Stream)
+await storage.put('bundles/app.tar', tarStream, {
+  headers: { contentType: 'application/x-tar' }
+});
+
+// 2. Download a file (returns fetch Response, stream is in .body)
+const res = await storage.get('bundles/app.tar');
+const downloadStream = res.body;
+
+// 3. List files (pass an object containing a prefix)
+const files = await storage.get({ prefix: 'bundles/' });
+console.log(files.contents);
+
+// 4. Retrieve metadata (HEAD request)
+const meta = await storage.stat('bundles/app.tar');
+console.log(meta.size, meta['x-amz-meta-version']);
+
+// 5. Delete an object
+await storage.del('bundles/app.tar');
+```
+
+## Features
+- **Closure-Based Design (No `this`)**: Every single client method can be safely destructured and decoupled without losing context: `const { get, put } = zs3(opts);`.
+- **Inlined Micro XML Parser**: Seamlessly converts S3 object listings without bloating your `node_modules` or running a heavy general-purpose parser.
+- **Robust AWS v4 Signatures**: Automatically manages query parameter alphabetical sorting, whitespace trimming, and strict URI hex-encoding under the hood.

package/index.ts

@@ -0,0 +1,152 @@
+export interface S3Config {
+  endpoint: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  bucket?: string;
+  region?: string;
+  [key: string]: any;
+}
+
+export interface S3Options {
+  headers?: Record<string, string>;
+  meta?: Record<string, string>;
+}
+
+export interface ListOptions {
+  prefix?: string;
+  maxKeys?: number;
+}
+
+export interface S3StatResponse extends Record<string, any> {
+  size: number;
+  mtime: Date;
+}
+
+const ALG_NAME = ('HMAC' + '');
+const ALG_HASH = ('SHA256' + '');
+const AWS4 = ('AWS4' + '');
+const SIGN_P = [AWS4, ALG_NAME, ALG_HASH].join('-');
+const RE_ISO_DATE = /[:-]|\.\d{3}/g;
+const RE_XML_TAGS = /<(\w)([-\w]*)(?:\/|[^>]*>((?:(?!<\1\2)[\s\S])*)<\/\1\2)>/gm;
+const RE_DASH_CASE = /\B[A-Z]/g;
+const RE_ENCODE_URI = /[!'()*]/g;
+const RE_LEADING_SLASHES = /^\/*/;
+
+const enc = new TextEncoder();
+const { subtle } = crypto;
+
+const toArrayBuffer = (d: any): ArrayBuffer =>
+  d instanceof ArrayBuffer ? d : d?.buffer?.constructor === ArrayBuffer ? d.buffer : enc.encode(d == null ? '' : `${d}`).buffer;
+
+export const toHex = (buf: ArrayBuffer | Uint8Array):string =>
+  Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+
+export const hmac = async (key: string | Uint8Array | ArrayBuffer, data: string): Promise<Uint8Array> => {
+  const cryptoKey = await subtle.importKey('raw', toArrayBuffer(key), { name: ALG_NAME, hash: ALG_HASH}, false, ['sign']);
+  return new Uint8Array(await subtle.sign(ALG_NAME, cryptoKey, enc.encode(data)));
+};
+
+export const hash = async (data: any) => toHex(await subtle.digest(ALG_HASH, toArrayBuffer(data)));
+
+const assignDashCase = (target: Record<string, string>, source: Record<string, any> | undefined, prefix: string): Record<string, string> => {
+  if (source) Object.keys(source).forEach(key => {
+    const name = (prefix + (key === "expires" ? key : key.replace(RE_DASH_CASE, "-$&"))).toLowerCase();
+    if (source[key] && typeof source[key] !== 'object') target[name] = `${source[key]}`;
+  });
+  return target;
+};
+
+const awsEncodeURI = (str: string): string =>
+  encodeURIComponent(str).replace(RE_ENCODE_URI, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+
+const parseXml = (str: string): any => {
+  const types: Record<string, any> = { "": "", "true": true, "false": false };
+  const m = [...str.matchAll(RE_XML_TAGS)];
+  return m.length ? m.reduce((acc: any, [, tag = '', suffix = '', content = '']) => {
+    const k = tag.toLowerCase() + suffix;
+    const v = types[content] ?? (isNaN(+content) ? parseXml(content) : +content);
+    acc[k] = Array.isArray(acc[k]) ? [...acc[k], v] : acc[k] != null ? [acc[k], v] : k === "contents" ? [v] : v;
+    return acc;
+  }, {}) : str;
+};
+
+export class S3XmlTransformStream extends TransformStream<Uint8Array, any> {
+  constructor() {
+    const decoder = new TextDecoder();
+    let acc = "";
+    super({
+      transform(chunk) { acc += decoder.decode(chunk, { stream: true }); },
+      flush(c) {
+        const res = parseXml((acc + decoder.decode()).trim());
+        c.enqueue(res?.listBucketResult || res);
+      }
+    });
+  }
+}
+
+export function zs3(opts: S3Config) {
+  const config = { region: 'us-east-1', bucket: '', ...opts };
+  const execute = async (method: string, path: string, body: any = null, options: S3Options = {}): Promise<Response | any> => {
+    const {
+      endpoint,
+      bucket,
+      region,
+      accessKeyId,
+      secretAccessKey
+    } = config;
+    const base = new URL(endpoint.startsWith('http') ? endpoint : `https://${endpoint.replace('://', '')}`);
+    const isoDate = new Date().toISOString().replace(RE_ISO_DATE, '');
+    const sDate = isoDate.slice(0, 8);
+    const pathname = bucket ? `/${bucket}/${path.replace(RE_LEADING_SLASHES, '')}` : path;
+    const isStream = body && typeof body.getReader === 'function';
+    const payloadHash = isStream ? 'UNSIGNED-PAYLOAD' : await hash(body || '');
+
+    const headers: Record<string, string> = assignDashCase(assignDashCase({
+      host: base.host,
+      'x-amz-date': isoDate,
+      'x-amz-content-sha256': payloadHash,
+      ...(body && !isStream ? { 'content-length': `${toArrayBuffer(body).byteLength}` } : {})
+    }, options.headers, ""), options.meta, "x-amz-meta-");
+
+    const [uri, query = ''] = pathname.split('?');
+    const sortedHeaders = Object.keys(headers).map(k => k.toLowerCase()).sort();
+    const sortedQuery = query ? query.split('&').sort().join('&') : '';
+
+    const canonical = [method, uri || '/', sortedQuery, sortedHeaders.map(k => `${k}:${headers[k]?.trim()}`).join('\n') + '\n', sortedHeaders.join(';'), payloadHash].join('\n');
+    const scope = `${sDate}/${region}/s3/aws4_request`;
+
+    const kSign = await hmac(await hmac(await hmac(await hmac(`${AWS4}${secretAccessKey}`, sDate), region), 's3'), 'aws4_request');
+    const signature = toHex(await hmac(kSign, [SIGN_P, isoDate, scope, await hash(canonical)].join('\n')));
+
+    headers['Authorization'] = `${SIGN_P} Credential=${accessKeyId}/${scope}, SignedHeaders=${sortedHeaders.join(';')}, Signature=${signature}`;
+
+    const res = await fetch(new URL(pathname, base), { method, headers, body });
+    if (!res.ok) throw new Error(`S3 Error: ${res.status} - ${await res.text()}`);
+
+    return method === 'HEAD' ? {
+      size: +res.headers.get("content-length")!,
+      mtime: new Date(res.headers.get("last-modified")!),
+      ...Object.fromEntries(res.headers)
+    } : res;
+  };
+
+  return {
+    get: async (keyOrOpts: string | ListOptions, options: S3Options = {}) => {
+      if (typeof keyOrOpts !== 'object' || keyOrOpts === null) {
+        return execute('GET', keyOrOpts, null, options);
+      }
+
+      const query = `?list-type=2&max-keys=${keyOrOpts.maxKeys || 1000}&prefix=${awsEncodeURI(keyOrOpts.prefix || '')}`;
+      const res = await execute('GET', query, null, options);
+
+      const reader = res.body?.pipeThrough(new S3XmlTransformStream()).getReader();
+
+      return (await reader?.read()).value
+    },
+    put: (path: string, body: any = null, options: S3Options = {}) => execute('PUT', path, body, options),
+    del: (path: string, options: S3Options = {}) => execute('DELETE', path, null, options),
+    stat: (path: string, options: S3Options = {}) => execute('HEAD', path, null, options),
+    execute,
+    config
+  };
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@focus-at/zs3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.4",
+  "description": "Zero-dependency micro S3 client built on Web Standards",
+  "homepage": "https://github.com/focus-at/zs3#readme",
+  "module": "index.ts",
+  "main": "./dist/zeros3.js",
+  "types": "./index.ts",
+  "bin": {
+    "zs3": "./dist/zs3.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": {
+        "typescript": "./index.ts",
+        "default": "./dist/zeros3.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bun build --minify ./index.ts --outfile=dist/zeros3.js",
+    "release": "npm version patch && git push origin main --tags",
+    "postinstall": "node -e \"if(!process.env.DISABLE_OPENCOLLECTIVE && !process.env.CI){process.stdout.write('\\u001b[35mThanks for installing ZeroS3! Consider giving it a star on GitHub: https://github.com\\u001b[0m\\n')}\""
+  },
+  "keywords": [
+    "s3",
+    "aws-s3",
+    "zeros3",
+    "zs3",
+    "micro",
+    "zero-dependency",
+    "web-standards",
+    "fetch",
+    "runtime",
+    "browser",
+    "cloudflare-workers",
+    "esm"
+  ],
+  "author": "Dmitry Zimin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:focus-at/zs3.git"
+  },
+  "bugs": {
+    "url": "https://github.com/focus-at/zs3/issues"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/focus-at/zs3/issues"
+    }
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/tests/index.test.ts

@@ -0,0 +1,141 @@
+import { describe, test, expect, afterEach, beforeEach } from "bun:test";
+import { zs3, hash, hmac, toHex } from "../index.ts";
+
+describe("ZeroS3 / zs3 Core Tests", () => {
+  const originalFetch = globalThis.fetch;
+
+  // Объявляем переменную для хранения инстанса
+  let storage: ReturnType<typeof zs3>;
+  let lastRequest = { url: null as URL | null, headers: {} as Record<string, string> };
+
+  const mockFetch = (xmlContent = "", status = 200) => {
+    globalThis.fetch = (async (url: URL, init?: RequestInit) => {
+      lastRequest.url = url;
+      lastRequest.headers = (init?.headers as Record<string, string>) || {};
+      return new Response(xmlContent, { status });
+    }) as unknown as typeof fetch;
+  };
+
+  // ИСПРАВЛЕНО: Сбрасываем и пересоздаем инстанс перед КАЖДЫМ тестом
+  beforeEach(() => {
+    storage = zs3({
+      endpoint: "127.0.0.1:9000",
+      accessKeyId: "mock-access-key",
+      secretAccessKey: "mock-secret-key",
+      bucket: "test-bucket",
+    });
+  });
+
+  // Хук afterEach гарантирует, что после каждого теста fetch вернется в исходное состояние
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("should correctly export core cryptographic utilities with strict check", async () => {
+    const signature = await hmac("secret", "data");
+    expect(signature).toBeInstanceOf(Uint8Array);
+    expect(toHex(signature)).toBe("1b2c16b75bd2a870c114153ccda5bcfca63314bc722fa160d690de133ccbb9db");
+    expect(await hash("hello zeros3")).toBe("dea9a435609aadbdaf641ddb2b0d1ad1d97263798769b6e43188d0ba57b79fad");
+  });
+
+  test("should correctly merge config defaults and reactively update on changes", async () => {
+    expect(storage.config.region).toBe("us-east-1");
+    expect(storage.config.bucket).toBe("test-bucket");
+
+    mockFetch();
+
+    // 1. Проверяем генерацию путей со старым конфигом
+    await storage.stat("file.txt");
+    expect(lastRequest.url?.pathname).toBe("/test-bucket/file.txt");
+    expect(lastRequest.url?.host).toBe("127.0.0.1:9000");
+    expect(lastRequest.headers["Authorization"]).toContain("/us-east-1/s3/aws4_request");
+
+    // 2. Меняем конфиг, подсовывая кривой эндпоинт с ://
+    storage.config.bucket = "dynamic-bucket";
+    storage.config.endpoint = "://zone.com";
+    storage.config.region = "eu-west-1";
+
+    // 3. Вызываем деструктурированный put — он обязан отработать реактивно
+    await storage.put("image.png", "payload");
+
+    expect(lastRequest.url?.host).toBe("zone.com");
+    expect(lastRequest.url?.protocol).toBe("https:");
+    expect(lastRequest.url?.pathname).toBe("/dynamic-bucket/image.png");
+    expect(lastRequest.headers["Authorization"]).toContain("/eu-west-1/s3/aws4_request");
+  });
+
+  test("should perfectly stream and parse large XML data and empty tags", async () => {
+    const xmlMock = `
+      <ListBucketResult>
+        <Name>test-bucket</Name>
+        <Prefix>production/</Prefix>
+        <MaxKeys>1000</MaxKeys>
+        <IsTruncated>false</IsTruncated>
+        <Marker></Marker>
+        <NextMarker/>
+        <Contents>
+          <Key>production/app.tar</Key>
+          <Size>31457280</Size>
+        </Contents>
+        <Contents>
+          <Key>production/config.json</Key>
+          <Size>2048</Size>
+        </Contents>
+      </ListBucketResult>
+    `;
+
+    globalThis.fetch = (async () => new Response(xmlMock, { status: 200 })) as unknown as typeof fetch;
+
+    const result = await storage.get({ prefix: "production/" });
+
+    // Top Level
+    expect(result.name).toBe("test-bucket");
+    expect(result.marker).toBe("");
+    expect(result.nextMarker).toBe("");
+    expect(result.isTruncated).toBe(false);
+    expect(result.maxKeys).toBe(1000);
+
+    // Array
+    expect(result.contents).toBeInstanceOf(Array);
+    expect(result.contents.length).toBe(2);
+    expect(result.contents[0].key).toBe("production/app.tar");
+    expect(result.contents[0].size).toBe(31457280);
+    expect(result.contents[1].key).toBe("production/config.json");
+    expect(result.contents[1].size).toBe(2048);
+  });
+
+  test("should perfectly stream and parse large XML data, empty tags and clean root prefix", async () => {
+    mockFetch(`
+      <ListBucketResult>
+        <Name>test-bucket</Name>
+        <Prefix></Prefix>
+        <MaxKeys>1000</MaxKeys>
+        <IsTruncated>false</IsTruncated>
+        <Marker></Marker>
+        <NextMarker/>
+        <Contents>
+          <Key>production/app.tar</Key>
+          <Size>31457280</Size>
+        </Contents>
+      </ListBucketResult>
+    `)
+
+    // Вызываем с ПУСТЫМ префиксом
+    const result = await storage.get({ prefix: "" });
+
+    // 1. ПРОВЕРКА ПРЕФИКСА В URL (убеждаемся, что пустой префикс не сломал строку)
+    expect(lastRequest.url?.search).toContain("prefix=");
+    expect(lastRequest.url?.pathname).toBe("/test-bucket/"); // Без двойных слэшей на конце!
+
+    // 2. ПРОВЕРКА ПУСТЫХ ТЕГОВ (убеждаемся, что они не стали числами 0 или null)
+    expect(result.prefix).toBe("");
+    expect(result.marker).toBe("");
+    expect(result.nextMarker).toBe("");
+
+    // 3. ПРОВЕРКА ТИПОВ И СТРУКТУРЫ ДАННЫХ
+    expect(result.isTruncated).toBe(false);
+    expect(result.maxKeys).toBe(1000);
+    expect(result.contents[0].key).toBe("production/app.tar");
+    expect(result.contents[0].size).toBe(31457280);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}