vinyl-records v0.0.7

Vinyl

A record store. Originals only!

What is Vinyl?

Vinyl is a library that adds relational mapping and a storage API for static, immutable application objects.

What does that mean?

Lets use a video game as an example use case: It doesn't make sense to save all the static game objects in a database along with users and other dynamic data. If it never changes throughout the lifecycle of the app, database work to retrieve it is unnecessary, and the database would grow unnecessarily large. Additionally, if many different users reference the same objects (say, 400 players in the game all have the "Sword of Destiny") you wouldn't want 400 copies of the "Sword of Destiny" saved in each user record either. With Vinyl, there is only ever 1 "Sword of Destiny", and instead, the 400 players save a reference to it. Every key on every object is relational, so even assembling the "Sword of Destiny" record is a matter of composing other unique records.

Non-relational data

id, name, description, and attributes are reserved for non-relational data like a name, email address, etc. Any other property is treated as a reference.

Card game example:

const { Record, RecordCollection } = require('vinyl-records');

new RecordCollection({
  rarities: [
    {
      id: 0,
      name: "Common"
    },
    {
      id: 1,
      name: "Rare"
    }
  ],
  types: [
    {
      id: 0,
      name: "Greater"
    },
    {
      id: 1,
      name: "Lesser"
    },
    {
      id: 2,
      name: "Mana"
    }
  ],
  cards: [
    {
      id: 0,
      name: "Boss",
      type: 0,
      rarity: 1
    },
    {
      id: 1,
      name: "Minion",
      type: 1,
      rarity: 0
    },
    {
      id: 2,
      name: "Field",
      type: 2,
      rarity: 0
    }
  ],
  currencies: [
    {
      id: 0,
      name: "Gold",
      rarity: 1
    },
    {
      id: 1,
      name: "Gems",
      rarity: 1
    }
  ]
});

All of the above data is kept in your application, and records are assembled only on an as-needed basis. A user of this card game might look like this in the database (or by the time it reaches the ORM):

{
  id: "12345",
  email: "test@example.com",
  cards: [0, 2],
  currencies: [0, 1],
  amounts: [246, 33]
}

RecordId

A RecordId is saved in whatever database you use, so that the data itself can be populated just once in your app (or to your app from storage/immutable db/blockchain/etc). Using Vinyl you can then Record.read(...), Record.search(...), and so-on, as an ORM-like tool for such data, while you can still use conventional tooling for typical mutable data (SQL, ActiveRecord, MongoDB, etc).

Get started

npm i vinyl-records