@vendit-dev/sequelize-binary-uuid
v1.1.0
Published
Makes it easy to implement binary(16) uuid's into Sequelize projects.
Downloads
4
Readme
sequelize-binary-uuid
This builds upon the binary-uuid package by making it easy to implement into Sequelize.
This package provides a few important exports:
- A
BINARY
type (binary(length)
). - A
BINARYUUID
field creator. - A
VIRTUALBINARYUUID
field creator. - A
withBinaryUUID
preset field creator.
This package makes it easy to use binary(16)
UUID's instead of CHAR(36)
which is the default. It also modifies the UUID
so that it is more performant when indexing which can lead to significant performance improvements over naive implementations.
Examples
Multiple examples are available in the examples folders.
Using withBinaryUUID
preset (recommended)
When utilizing the preset
, the model will be created with an id
field which is the primaryKey
and is a generated binary(16)
uuid value.
In addition, the model will have a uuid
virtual field which is the string version of the uuid.
import Sequelize from "sequelize";
import { withBinaryUUID } from "sequelize-binary-uuid";
// define sequelize...
const User = sequelize.define(
"User",
withBinaryUUID(
{
// any other fields here
someKey: Sequelize.DataTypes.TEXT
},
{
primaryID: "id", // default
virtualID: "uuid", // default
field: {
// optionally provide extra parameters to the
// `primaryID` binary field
primaryKey: true
// primaryKey: true is required to make it a
// primaryKey!
}
}
)
);
Once you have done this, you may interact with the table:
sequelize
.sync({ force: true })
.then(() =>
Promise.all([
User.create({ someKey: "one" }),
User.create({ someKey: "two" }),
User.create({ someKey: "three" })
])
)
.then(() => User.findAll())
.then(users => users.map(user => user.get({ plain: true })))
.then(console.log);
[
{
uuid: '8cde7820-04c1-11e9-8d40-0d6e8c185c6c',
id: <Buffer 11 e9 04 c1 8c de 78 20 8d 40 0d 6e 8c 18 5c 6c>,
someKey: 'one',
createdAt: 2018-12-21T01:41:35.000Z,
updatedAt: 2018-12-21T01:41:35.000Z
},
{
uuid: '8cdec640-04c1-11e9-8d40-0d6e8c185c6c',
id: <Buffer 11 e9 04 c1 8c de c6 40 8d 40 0d 6e 8c 18 5c 6c>,
someKey: 'two',
createdAt: 2018-12-21T01:41:35.000Z,
updatedAt: 2018-12-21T01:41:35.000Z
},
{
uuid: '8cdec641-04c1-11e9-8d40-0d6e8c185c6c',
id: <Buffer 11 e9 04 c1 8c de c6 41 8d 40 0d 6e 8c 18 5c 6c>,
someKey: 'three',
createdAt: 2018-12-21T01:41:35.000Z,
updatedAt: 2018-12-21T01:41:35.000Z
}
]
IMPORTANT: It is important to note here that the
uuid
field isVIRTUAL
- this means it is NOT stored in the database and is only provided as a convenience.
Creating a Binary UUID
Using the BINARYUUID
helper we can define a field as being a binary UUID. This will use a binary(16)
type and will generate a uuid by default if none is provided.
import Sequelize from "sequelize";
import { BINARYUUID } from "sequelize-binary-uuid";
// define sequelize...
const User = sequelize.define("User", {
// ... your model definition ...
binaryUUID: BINARYUUID({
// field params here...
allowNull: true
})
});
NOTE: If you set
allowNull
totrue
then a binary uuid will not be generated when the field is not provided. You will need to provide one yourself.
Creating a UUID Virtual Field
Using VIRTUALBINARYUUID
will make it easy to provide a VIRTUAL
field which resolves to the initial string version of the uuid for the given field.
VIRTUALBINARYUUID
expects two arguments. First, the target
field (the binary uuid) then the source
field (the string/virtual field).
import Sequelize from "sequelize";
import { BINARYUUID, VIRTUALBINARYUUID } from "sequelize-binary-uuid";
// define sequelize...
const User = sequelize.define("User", {
// ... your model definition ...
binaryUUID: BINARYUUID({
allowNull: false
}),
stringUUID: VIRTUALBINARYUUID("binaryUUID", "stringUUID")
});
Using the BINARY
type
If you wish to construct your own binary type and/or binary UUID values, you can follow the example below.
import Sequelize from "sequelize";
import { BINARY, getBinaryUUID } from "sequelize-binary-uuid";
// define sequelize...
const User = sequelize.define("User", {
// ... your model definition ...
customBinaryUUID: {
type: BINARY(16)
}
});
// .. later
User.create({
customBinaryUUID: getBinaryUUID()
});
Helper Exports
As a convenience, this package also re-exports some helpers from binary-uuid
, as well as some helper functions.
import {
getBinaryUUID,
fromBinaryUUID,
toBinaryUUID
} from "sequelize-binary-uuid";
const buf = getBinaryUUID();
const uuid = fromBinaryUUID();
const buf2 = toBinaryUUID(uuid);