{"_id":"@bradenmacdonald/s3-lite-client","_rev":"3-966789d7c52ccd9a83dde5373bb39300","name":"@bradenmacdonald/s3-lite-client","dist-tags":{"latest":"1.0.0"},"versions":{"0.9.5":{"name":"@bradenmacdonald/s3-lite-client","version":"0.9.5","license":"MIT","_id":"@bradenmacdonald/s3-lite-client@0.9.5","maintainers":[{"name":"bradenmacdonald","email":"braden@bradenmacdonald.com"}],"homepage":"https://jsr.io/@bradenmacdonald/s3-lite-client","bugs":{"url":"https://github.com/bradenmacdonald/s3-lite-client/issues"},"dist":{"shasum":"830ad2ac188032a45208b714aab19626f6ecd643","tarball":"https://registry.npmjs.org/@bradenmacdonald/s3-lite-client/-/s3-lite-client-0.9.5.tgz","fileCount":45,"integrity":"sha512-Kfgwjp+80C9Ell71PuAY0Yy6GvM33vhMFMgmIreelkhkZO4pg1C5ovVNwTDrsDg7nEqBH71e4yVrzM2U1666Ag==","signatures":[{"sig":"MEUCIQDLNt1HuZBLpFt0tt6Ny9B0/oTzOEWs/XLNWNeFsVTWzAIgVY5WWwJJ1qFGcUSFIDJWS5V0Wj9x+pvDZmPJn4oULdg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":258458},"type":"module","exports":{".":{"types":"./_dist/mod.d.ts","default":"./mod.js"}},"gitHead":"13cdf298b02f80e568e4fc79ca7bfa912fa12e8b","_npmUser":{"name":"bradenmacdonald","email":"braden@bradenmacdonald.com"},"repository":{"url":"git+https://github.com/bradenmacdonald/s3-lite-client.git","type":"git"},"_npmVersion":"11.10.0","description":"A lightweight S3 client.","directories":{},"_nodeVersion":"24.1.0","dependencies":{},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/s3-lite-client_0.9.5_1774805464836_0.07417048571449092","host":"s3://npm-registry-packages-npm-production"}},"0.9.6":{"name":"@bradenmacdonald/s3-lite-client","version":"0.9.6","license":"MIT","_id":"@bradenmacdonald/s3-lite-client@0.9.6","maintainers":[{"name":"bradenmacdonald","email":"braden@bradenmacdonald.com"}],"homepage":"https://jsr.io/@bradenmacdonald/s3-lite-client","bugs":{"url":"https://github.com/bradenmacdonald/s3-lite-client/issues"},"dist":{"shasum":"1077115c8eaa2eaf1467d8ca55221d3bd8d9cb82","tarball":"https://registry.npmjs.org/@bradenmacdonald/s3-lite-client/-/s3-lite-client-0.9.6.tgz","fileCount":46,"integrity":"sha512-Ec7u0jGd8BoaBdK847JFaWja6xeRtVPPe0faMuPaIVeE9Szecu16vNyUJNRrIMwLwsEM3ghLSgnkHySh399pUg==","signatures":[{"sig":"MEYCIQC+TlSJxEcL6xOw98j5YeU3d+CyEWMk8f0qREewi6IM/gIhAJ/t/HmxXSBKL1C+aVzK8NMIIqLpVIqEiQTQkeVWjhm0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bradenmacdonald%2fs3-lite-client@0.9.6","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":268353},"type":"module","exports":{".":{"types":"./_dist/mod.d.ts","default":"./mod.js"}},"gitHead":"6e4763f6792c5eb0be0bf5051a95164f0aee4b71","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:40f500c1-86e9-4ad8-a232-1ee561fb8c9e"}},"repository":{"url":"git+https://github.com/bradenmacdonald/s3-lite-client.git","type":"git"},"_npmVersion":"11.9.0","description":"A lightweight S3 client.","directories":{},"_nodeVersion":"24.14.0","dependencies":{},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/s3-lite-client_0.9.6_1774815714095_0.3880808469167387","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@bradenmacdonald/s3-lite-client","version":"1.0.0","homepage":"https://jsr.io/@bradenmacdonald/s3-lite-client","type":"module","dependencies":{},"exports":{".":{"types":"./_dist/mod.d.ts","default":"./mod.js"}},"license":"MIT","description":"A lightweight S3 client.","repository":{"type":"git","url":"git+https://github.com/bradenmacdonald/s3-lite-client.git"},"sideEffects":false,"gitHead":"7cd52c07a78cdefc8d890dc5b5dc95f65ea20bc5","_id":"@bradenmacdonald/s3-lite-client@1.0.0","bugs":{"url":"https://github.com/bradenmacdonald/s3-lite-client/issues"},"_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-j83jujGwsJDfXPybSF+wA3orT9hO9xIM1HseCk9IDCmdn3zU2WdCK3vk6DSuys7VilB/cVNXcmb7zOpUgor/jQ==","shasum":"ed1cc2a341710c2d97184819c46fcb587cfd72e2","tarball":"https://registry.npmjs.org/@bradenmacdonald/s3-lite-client/-/s3-lite-client-1.0.0.tgz","fileCount":49,"unpackedSize":303762,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bradenmacdonald%2fs3-lite-client@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDHqu4N2iAwMjoMYGXfjB+YO3/VY+Dg6LJUiZRoh2mIGwIhALVQDuLvGqQfptDE3pj9OXG6aogHzIufS3xteOyqynNa"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:40f500c1-86e9-4ad8-a232-1ee561fb8c9e"}},"directories":{},"maintainers":[{"name":"bradenmacdonald","email":"braden@bradenmacdonald.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/s3-lite-client_1.0.0_1786638319754_0.1007454201425717"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T17:31:04.677Z","modified":"2026-08-13T16:25:20.232Z","0.9.5":"2026-03-29T17:31:04.993Z","0.9.6":"2026-03-29T20:21:54.235Z","1.0.0":"2026-08-13T16:25:19.891Z"},"bugs":{"url":"https://github.com/bradenmacdonald/s3-lite-client/issues"},"license":"MIT","homepage":"https://jsr.io/@bradenmacdonald/s3-lite-client","repository":{"type":"git","url":"git+https://github.com/bradenmacdonald/s3-lite-client.git"},"description":"A lightweight S3 client.","maintainers":[{"name":"bradenmacdonald","email":"braden@bradenmacdonald.com"}],"readme":"# s3-lite-client\n\n![MIT License](https://img.shields.io/npm/l/%40bradenmacdonald%2Fs3-lite-client)\n[![no dependencies](https://depx.co/api/badge/@bradenmacdonald/s3-lite-client)](https://depx.co/pkg/@bradenmacdonald/s3-lite-client)\n[![minimized gzipped size](https://img.shields.io/bundlejs/size/%40bradenmacdonald%2Fs3-lite-client)](https://bundlejs.com/?q=%40bradenmacdonald%2Fs3-lite-client&treeshake=%5B*%5D&text=%22const+s3client+%3D+new+S3Client%28%7B%5Cn++endPoint%3A+%5C%22https%3A%2F%2Fs3.us-east-1.amazonaws.com%5C%22%2C%5Cn++region%3A+%5C%22us-east-1%5C%22%2C%5Cn++bucket%3A+%5C%22openalex%5C%22%2C%5Cn%7D%29%3B%5Cn%5Cn%2F%2F+Log+data+about+each+object+found+under+the+%27data%2Fconcepts%2F%27+prefix%3A%5Cnfor+await+%28const+obj+of+s3client.listObjects%28%7B+prefix%3A+%5C%22data%2Fconcepts%2F%5C%22+%7D%29%29+%7B%5Cn++console.log%28obj%29%3B%5Cn%7D%22)\n[![JSR Version](https://jsr.io/badges/@bradenmacdonald/s3-lite-client)](https://jsr.io/@bradenmacdonald/s3-lite-client)\n[![JSR Downloads](https://jsr.io/badges/@bradenmacdonald/s3-lite-client/total-downloads)](https://jsr.io/@bradenmacdonald/s3-lite-client)\n[![NPM Version](https://img.shields.io/npm/v/%40bradenmacdonald%2Fs3-lite-client)](https://www.npmjs.com/package/@bradenmacdonald/s3-lite-client)\n\nThis is a lightweight S3 (object storage) client for JavaScript runtimes (Deno, Node 22+, Bun, browsers, etc.). It is\ndesigned to offer all the key features you may need, without bloat. It should work with any JavaScript runtime that\nsupports the `fetch` API, web streams API, and ES modules (ESM).\n\n**Key features**:\n\n- Has **no dependencies** and minifies to about 21kB (< 8 kB gzipped).\n  - For comparison, the official `@aws-sdk/client-s3` has\n    [56 dependencies and weighs 399 kB (94 kB gzipped)](https://bundlephobia.com/package/@aws-sdk/client-s3@3.758.0) at\n    the time of writing.\n- Works with any S3-compatible storage service: AWS S3, MinIO, Cloudflare R2, Backblaze B2, DigitalOcean Spaces,\n  Supabase storage, etc.\n- Implemented in TypeScript and fully typed.\n- 100% MIT licensed, derived from the excellent [MinIO JavaScript Client](https://github.com/minio/minio-js).\n\n## Supported functionality\n\n- Authenticated or unauthenticated requests\n- List objects: `for await (const object of client.listObjects(options)) { ... }`\n  - Handles pagination transparently\n  - Supports filtering using a prefix\n  - Supports [grouping using a delimiter](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html)\n    (use `client.listObjectsGrouped(...)`)\n- Check if an object exists: `client.exists(\"key\")`\n- Get metadata about an object: `client.statObject(\"key\")`\n  - Can include custom headers in the request:\n    `client.statObject(\"key\", { headers: { 'x-amz-checksum-mode': 'ENABLED' } })`\n- Download an object: `client.getObject(\"key\", options)`\n  - This just returns a standard HTTP `Response` object, so for large files, you can opt to consume the data as a stream\n    (use the `.body` property).\n- Download a partial object: `client.getPartialObject(\"key\", options)`\n  - Like `getObject`, this also supports streaming the response if you want to.\n- Upload an object: `client.putObject(\"key\", streamOrData, options)`\n  - Can upload from a `string`, `Uint8Array`, or `ReadableStream`\n  - Can split large uploads into multiple parts, and uploads a limited number of parts in parallel.\n  - Uploads of 64MB or more are split into 64MB parts by default. Since S3 allows at most 10,000 parts, that supports\n    objects up to 640GB; to upload something bigger, or to stream something bigger without passing `size`, pass a larger\n    `partSize` (up to 5GB).\n  - Can set custom headers, ACLs, and other metadata on the new object (example below).\n- Copy an object: `client.copyObject({ sourceKey: \"source\", options }, \"dest\", options)`\n  - Can copy between different buckets.\n- Delete an object: `client.deleteObject(\"key\")`\n- Create pre-signed URLs: `client.presignedGetObject(\"key\", options)` or\n  `client.getPresignedUrl(method, \"key\", options)`\n- Create pre-signed POST policy: `client.presignedPostObject(\"key\", options)` for direct browser uploads\n- Check if a bucket exists: `client.bucketExists(\"bucketName\")`\n- Create a new bucket: `client.makeBucket(\"bucketName\")`\n- Remove a bucket: `client.removeBucket(\"bucketName\")`\n\n## Installation\n\n- Deno: `deno add @bradenmacdonald/s3-lite-client`\n- Deno (no install): `import { S3Client } from \"jsr:@bradenmacdonald/s3-lite-client@1.0.0\";`\n- NPM: `npm add @bradenmacdonald/s3-lite-client`\n- Yarn: `yarn add jsr:@bradenmacdonald/s3-lite-client`\n- pnpm: `pnpm add jsr:@bradenmacdonald/s3-lite-client`\n- Bun: `bunx jsr add @bradenmacdonald/s3-lite-client`\n- Browser:\n  ```html\n  <script type=\"module\">\n  import { S3Client } from \"https://esm.sh/jsr/@bradenmacdonald/s3-lite-client@1.0.0\";\n  // Or:\n  const { S3Client } = await import(\"https://esm.sh/jsr/@bradenmacdonald/s3-lite-client@1.0.0\");\n  </script>\n  ```\n\n## Usage Examples (Quickstart)\n\nList data files from a public data set on Amazon S3:\n\n```typescript\nimport { S3Client } from \"@bradenmacdonald/s3-lite-client\";\n\nconst s3client = new S3Client({\n  endPoint: \"https://s3.us-east-1.amazonaws.com\",\n  region: \"us-east-1\",\n  bucket: \"openalex\",\n});\n\n// Log data about each object found under the 'data/concepts/' prefix:\nfor await (const obj of s3client.listObjects({ prefix: \"data/concepts/\" })) {\n  console.log(obj);\n}\n// {\n//   type: \"Object\",\n//   key: \"data/concepts/updated_date=2024-01-25/part_000.gz\",\n//   etag: \"2c9b2843c8d2e9057656e1af1c2a92ad\",\n//   size: 44105,\n//   lastModified: 2024-01-25T22:57:43.000Z\n// },\n// ...\n\n// Or, to get all the keys (paths) as an array:\nconst keys = await Array.fromAsync(s3client.listObjects(), (entry) => entry.key);\n// keys = [\n//  \"data/authors/manifest\",\n//  \"data/authors/updated_date=2023-06-08/part_000.gz\",\n//  ...\n// ]\n```\n\nUploading and downloading a file using a local MinIO server:\n\n```typescript\nimport { S3Client } from \"@bradenmacdonald/s3-lite-client\";\n\n// Connecting to a local MinIO server:\nconst s3client = new S3Client({\n  endPoint: \"http://localhost:9000\",\n  region: \"dev-region\",\n  bucket: \"dev-bucket\",\n  accessKey: \"AKIA_DEV\",\n  secretKey: \"secretkey\",\n});\n\n// Upload a file:\nawait s3client.putObject(\"test.txt\", \"This is the contents of the file.\");\n\n// Now download it\nconst result = await s3client.getObject(\"test.txt\");\n// and stream the results to a local file:\nconst localOutFile = await Deno.open(\"test-out.txt\", { write: true, createNew: true });\nawait result.body!.pipeTo(localOutFile.writable);\n// or instead of streaming, you can consume the whole file into memory by awaiting\n// result.text(), result.blob(), result.arrayBuffer(), or result.json()\n```\n\nCreating a bucket on the S3 service of a local supabase development server:\n\n```ts\nconst client = new S3Client({\n  endPoint: \"http://127.0.0.1:54321/storage/v1/s3\",\n  region: \"local\",\n  accessKey: \"paste from output of supabase start\",\n  secretKey: \"paste from output of supabase start\",\n});\nawait client.makeBucket(\"my-bucket\");\n```\n\nSet ACLs, Content-Type, custom metadata, etc. during upload:\n\n```ts\nawait s3client.putObject(\"key\", streamOrData, {\n  metadata: {\n    \"x-amz-acl\": \"public-read\",\n    \"x-amz-meta-custom\": \"value\",\n  },\n});\n```\n\nCreate a presigned POST policy for direct uploads from a browser:\n\n```ts\n// Create a presigned POST policy\nconst { url, fields } = await s3client.presignedPostObject(\"my-file.txt\", {\n  expirySeconds: 3600, // URL expires in 1 hour\n  fields: {\n    \"Content-Type\": \"text/plain\",\n  },\n});\n\n// In the browser, use the policy for direct uploads:\nconst formData = new FormData();\n// Add all required fields from the presigned POST\nObject.entries(fields).forEach(([key, value]) => {\n  formData.append(key, value);\n});\n// Add the file content\nformData.append(\"file\", fileInput.files[0]);\n\n// Upload the object using the presigned POST\nconst response = await fetch(url, {\n  method: \"POST\",\n  body: formData,\n});\n\nif (response.ok) {\n  console.log(\"File uploaded successfully!\");\n}\n```\n\nFor more examples, check out the tests in [`integration.ts`](./integration.ts)\n\n## Developer notes\n\nTo run the tests, please use:\n\n```sh\ndeno lint && deno test\n```\n\nTo format the code, use:\n\n```sh\ndeno fmt\n```\n\nTo run the integration tests, first start MinIO with this command:\n\n```sh\ndocker run --rm -e MINIO_ROOT_USER=AKIA_DEV -e MINIO_ROOT_PASSWORD=secretkey -e MINIO_REGION_NAME=dev-region -p 9000:9000 -p 9001:9001 --entrypoint /bin/sh minio/minio:RELEASE.2025-02-28T09-55-16Z -c 'mkdir -p /data/dev-bucket && minio server --console-address \":9001\" /data'\n```\n\nThen while MinIO is running, run\n\n```sh\ndeno test --allow-net integration.ts\n```\n\n(If you encounter issues and need to debug what MinIO is seeing, run these two commands:)\n\n```sh\nmc alias set localdebug http://localhost:9000 AKIA_DEV secretkey\nmc admin trace --verbose --all localdebug\n```\n","readmeFilename":"README.md"}