@focus-at/zs3 0.0.0-stage → 0.0.5

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/dist/zeros3.js

@@ -0,0 +1,5 @@
+var y="HMAC",m="SHA256",b="AWS4",U=[b,y,m].join("-"),M=/[:-]|\.\d{3}/g,W=/<(\w)([-\w]*)(?:\/|[^>]*>((?:(?!<\1\2)[\s\S])*)<\/\1\2)>/gm,v=/\B[A-Z]/g,X=/[!'()*]/g,k=/^\/*/,H=new TextEncoder,{subtle:A}=crypto,S=(e)=>e instanceof ArrayBuffer?e:e?.buffer?.constructor===ArrayBuffer?e.buffer:H.encode(e==null?"":`${e}`).buffer,I=(e)=>Array.from(new Uint8Array(e)).map((n)=>n.toString(16).padStart(2,"0")).join(""),u=async(e,n)=>{let r=await A.importKey("raw",S(e),{name:y,hash:m},!1,["sign"]);return new Uint8Array(await A.sign(y,r,H.encode(n)))},j=async(e)=>I(await A.digest(m,S(e))),C=(e,n,r)=>{if(n)Object.keys(n).forEach((t)=>{let s=(r+(t==="expires"?t:t.replace(v,"-$&"))).toLowerCase();if(n[t]&&typeof n[t]!=="object")e[s]=`${n[t]}`});return e},Q=(e)=>encodeURIComponent(e).replace(X,(n)=>`%${n.charCodeAt(0).toString(16).toUpperCase()}`),T=(e)=>{let n={"":"",true:!0,false:!1},r=[...e.matchAll(W)];return r.length?r.reduce((t,[,s="",a="",i=""])=>{let o=s.toLowerCase()+a,c=n[i]??(isNaN(+i)?T(i):+i);return t[o]=Array.isArray(t[o])?[...t[o],c]:t[o]!=null?[t[o],c]:o==="contents"?[c]:c,t},{}):e};class B extends TransformStream{constructor(){let e=new TextDecoder,n="";super({transform(r){n+=e.decode(r,{stream:!0})},flush(r){let t=T((n+e.decode()).trim());r.enqueue(t?.listBucketResult||t)}})}}function Y(e){let n={region:"us-east-1",bucket:"",...e},r=async(t,s,a=null,i={})=>{let{endpoint:o,bucket:c,region:w,accessKeyId:G,secretAccessKey:K}=n,h=new URL(o.startsWith("http")?o:`https://${o.replace("://","")}`),l=new Date().toISOString().replace(M,""),x=l.slice(0,8),E=c?`/${c}/${s.replace(k,"")}`:s,R=a&&typeof a.getReader==="function",D=R?"UNSIGNED-PAYLOAD":await j(a||""),f=C(C({host:h.host,"x-amz-date":l,"x-amz-content-sha256":D,...a&&!R?{"content-length":`${S(a).byteLength}`}:{}},i.headers,""),i.meta,"x-amz-meta-"),[N,L=""]=E.split("?"),d=Object.keys(f).map((p)=>p.toLowerCase()).sort(),z=L?L.split("&").sort().join("&"):"",O=[t,N||"/",z,d.map((p)=>`${p}:${f[p]?.trim()}`).join(`
+`)+`
+`,d.join(";"),D].join(`
+`),_=`${x}/${w}/s3/aws4_request`,q=await u(await u(await u(await u(`${b}${K}`,x),w),"s3"),"aws4_request"),P=I(await u(q,[U,l,_,await j(O)].join(`
+`)));f.Authorization=`${U} Credential=${G}/${_}, SignedHeaders=${d.join(";")}, Signature=${P}`;let g=await fetch(new URL(E,h),{method:t,headers:f,body:a});if(!g.ok)throw Error(`S3 Error: ${g.status} - ${await g.text()}`);return t==="HEAD"?{size:+g.headers.get("content-length"),mtime:new Date(g.headers.get("last-modified")),...Object.fromEntries(g.headers)}:g};return{get:async(t,s={})=>{if(typeof t!=="object"||t===null)return r("GET",t,null,s);let a=`?list-type=2&max-keys=${t.maxKeys||1000}&prefix=${Q(t.prefix||"")}`;return(await(await r("GET",a,null,s)).body?.pipeThrough(new B).getReader()?.read()).value},put:(t,s=null,a={})=>r("PUT",t,s,a),del:(t,s={})=>r("DELETE",t,null,s),stat:(t,s={})=>r("HEAD",t,null,s),execute:r,config:n}}export{B as S3XmlTransformStream,j as hash,u as hmac,I as toHex,Y as zs3};

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,68 @@
 {
   "name": "@focus-at/zs3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.5",
+  "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"
+    }
+  ],
+  "files": [
+    "dist",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}