@hisorange/s3odm NPM

S3 Object Data Mappper

S3 ODM Banner

Just a super light weight "client", currently only implements a handful of interactions. It's main goal to provide a non bloated way to interact with S3 buckets.

Getting Started

yarn add @hisorange/s3odm
# Or
npm i @hisorange/s3odm

Example Usage

import { S3ODM, Document } from '@hisorange/s3odm';

const ACCESS_KEY = 'XXXXX';
const SECRET_KEY = 'XXXXY';
const DOMAIN = '994b72fa8e67bc4167137357a2dd8763.r2.cloudflarestorage.com';
const BUCKET = 'my-database';

type User = {
  name: string;
  email: string;
  lastSeenAt: number;
} & Document;

const odm = new S3ODM(ACCESS_KEY, SECRET_KEY, DOMAIN, BUCKET);

(async () => {
  // Create a repository which maps the documents to a prefix within the bucket
  const repository = odm.createRepository<User>('users');

  // Create new document from POJOs
  const doc = await repository.insert({
    name: 'Jane Doe',
    email: 'jane@does.com',
  });

  // Read a record by _id property
  await repository.findById(doc._id);

  // Load every record with a single call
  for (const user of await repository.findAll()) {
    // Update existing records
    repository.update({
      ...user,
      lastSeenAt: Date.now(),
    });
  }
})();

Magic _id property

Each document gets an _id property assigned on read / write time, the identifier is the same as the document's path name without the table as prefix.

Ideology (Why)

S3 is a key value storage, but we always think about it as a file storage (as it's intended to be one). My problem was simple, the project I was working on had to store a set of JSON documents in a persistent and reliable storage, but it could not be a traditional database because the JSON files were the descriptors for the database. And S3 is a perfect solution for this, you can use it as a cheap and reliable solution to manage sets of data. But of course only if the query performance is not a problem!

Please don't try to create an e-commerce site with S3 as database, it will be slow and expensive for that kind of load, but if you wanna store and work with data which is not often needed but has to be available and reliable, then enjoy this repository.It will abstract the S3 finickiness away from you, and provide a super lightweight client to do so.

Also I am well aware of the AWS S3 SDK library, but it is 4.08 MB at the time of writing, while this library is 9kb as it is.

One more thing, don't forget to be awesome! ^.^