Instant.dev

JavaScript + Postgres API Framework with ORM, Migrations and Vectors

ORM
instant-dev/instantinstant.devinstant.dev

README

instant


npm

JavaScript + Postgres API Framework with ORM, Migrations and Vectors


[instant.dev](https://instant.dev) provides a fast, reliable and
battle-tested ORM and migration management system for Postgres 13+ built in
JavaScript. For those familiar with Ruby on Rails, instant.dev adds
functionality similar to ActiveRecord to the Node.js, Deno and Bun ecosystems.
We have been using it since 2016 in production at
Autocode where it has managed over 1 billion records in
a 4TB AWS Aurora Postgres instance.

With instant.dev you can:

- Add the Instant ORM and migrations to
  your existing JavaScript or TypeScript project
- Scaffold new Postgres-backed API projects from scratch using
  Instant API
- Generate new migrations, models and endpoints
- Migrate remote databases and deploy in a single step
- Connect to any PostgreSQL host: AWS RDS, Railway, Vercel Postgres, Neon,
  Supabase
- Instantly deploy to Vercel

Are you interested in connecting? Join us on Discord or follow us on
X, @instantdevs.



Features


- [CRUD operations](#crud-operations)
  - Create, Read, Update and Destroy records easily
- [Vector fields](#vector-fields)
  - Build AI-integrated applications and add search by easily creating, updating and
    querying against vectorized representations of your data
- [Query composition](#query-composition)
  - Build complex SELECT and UPDATE queries with many layers of nested joins and
    conditional statements
- [Transactions](#transactions)
  - Ensure data consistency within logical transaction blocks that can be rolled
    back to prevent writing orphaned data
- [Input validation](#input-validation)
  - Synchronously validate object fields to ensure the right data is stored
- [Relationship verification](#relationship-verification)
  - Asynchronously validate relationships between one or more fields and
    external resources before saving
- [Calculated and hidden fields](#calculated-and-hidden-fields)
  - Automatically populate object fields based on existing data
- [Lifecycle callbacks](#lifecycle-callbacks)
  - Execute custom logic beforeSave(), afterSave(), beforeDestroy() and
    afterDestroy() to perform necessary build and teardown steps inside of
    transactions
- [Migrations](#migrations)
  - Manage local database state via the filesystem to make branched git
    development a breeze
- [Seeding](#seeding)
  - Provide custom JSON files so that all developers can share the same test
    data across development, testing and staging environments
- [Code generation](#code-generation)
  - Automatically generate models, migrations and endpoints for your project

Table of Contents


1. Installation and Usage
2. Getting Started
3. [Using the instant CLI](#using-the-instant-cli)
4. Using the Instant ORM
5. Feature breakdown
6. Kits
   1. Kit: auth
      1. Kit: auth on Autocode
      2. Kit: auth on Vercel
7. Acknowledgements

Installation and Usage


  1. ```shell
  2. npm i instant.dev -g
  3. cd ~/projects/my-awesome-project
  4. instant init
  5. ```

That's it! The command line tool will walk you through the process of
initializing your instant.dev project. It will;

- Automatically detect whether this is a new project or an existing one
- Scaffold a new Vercel or Autocode
  project, if necessary
- Ask for your local database credentials
- Initialize necessary files in the _instant/ directory of your project
- Create an initial migration

To install the basic auth kit which comes with a User and AccessToken
model and associated user registration and login endpoints, use:

  1. ```shell
  2. instant kit auth
  3. ```

You can read more in Kit: auth

Using the instant CLI


You can look up documentation for the instant command line utility at any
point by running instant or instant help. The most commonly used methods
are:

- instant g:model to create a new model
- instant g:relationship to create one-to-one or one-to-many relationships
  between models
- instant g:endpoint to automatically scaffold Vercel or Autocode endpoints,
  if applicable
- instant db:migrate to run migrations
- instant db:rollback to rollback migrations
- instant db:rollbackSync to rollback to last synchronized (filesystem x
  database) migration
- instant db:bootstrap to reset your database, run migrations, and seed data
- instant db:add to add remote databases (AWS RDS, Railway, Vercel Postgres,
  Neon, Supabase)
- instant serve to run your server using Vercel, Autocode or the command
  specified in package.json["scripts"]["start"]
- instant sql is a shortcut to psql into any of your databases
- instant deploy to run outstanding migrations and deploy to Vercel or
  Autocode

Using the Instant ORM


Full documentation for the ORM can be found in the
@instant.dev/orm repository. Here's
a quick overview of using the ORM:

Importing with CommonJS:

  1. ```javascript
  2. const InstantORM = require('@instant.dev/orm');
  3. const Instant = new InstantORM();
  4. ```

Importing with ESM:

  1. ```javascript
  2. import InstantORM from '@instant.dev/orm';
  3. const Instant = new InstantORM();
  4. ```

Using the ORM:

  1. ```javascript
  2. // Connect to your database
  3. // Defaults to using instant/db.json[process.env.NODE_ENV || 'development']
  4. await Instant.connect();

  6. // Get the user model: can also use 'user', 'users' to same effect
  7. const User = Instant.Model('User');

  9. // Create a user
  10. let user = await User.create({username: 'Billy'});

  12. // log user JSON
  13. // {id: 1, username: 'Billy', created_at: '...', updated_at: '...'}
  14. console.log(user.toJSON());

  16. // Create multiple models at once
  17. const UserFactory = Instant.ModelFactory('User');
  18. let createdUsers = await UserFactory.create([
  19.   {username: 'Sharon'},
  20.   {username: 'William'},
  21.   {username: 'Jill'}
  22. ]);

  24. // Retrieves users with username containing the string 'ill'
  25. let users = await User.query()
  26.   .where({username__icontains: 'ill'})
  27.   .orderBy('username', 'ASC')
  28.   .select();

  30. // [{username: 'Billy'}, {username: 'Jill'}, {username: 'William'}]
  31. console.log(users.toJSON());

  33. users[0].set('username', 'Silly Billy');
  34. await users[0].save();

  36. // [{username: 'Silly Billy'}, {username: 'Jill'}, {username: 'William'}]
  37. console.log(users.toJSON());
  38. ```

Feature breakdown


CRUD operations


  1. ```javascript
  2. const User = Instant.Model('User');

  4. /* Create */
  5. let user = await User.create({
  6.   email: 'keith@instant.dev',
  7.   username: 'keith'
  8. });
  9. // Can also use new keyword to create, must save after
  10. user = new User({
  11.   email: 'keith@instant.dev',
  12.   username: 'keith'
  13. });
  14. await user.save();

  16. /* Read */
  17. user = await User.find(1); // uses id
  18. user = await User.findBy('email', 'keith@instant.dev');
  19. user = await User.query()
  20.   .where({email: 'keith@instant.dev'})
  21.   .first();
  22. let users = await User.query()
  23.   .where({email: 'keith@instant.dev'})
  24.   .select();

  26. /* Update */
  27. user.set('username', 'keith_h');
  28. await user.save();

  30. // Update by reading from data
  31. user.read({username: 'keith_h'});
  32. await user.save();

  34. // Update or Create By
  35. user = await User.updateOrCreateBy(
  36.   'username',
  37.   {username: 'keith', email: 'keith+new@instant.dev'}
  38. );

  40. // Update query: this will bypass validations and verifications
  41. users = await User.query()
  42.   .where({username: 'keith_h'})
  43.   .update({username: 'keith'});

  45. /* Destroy */
  46. await user.destroy();
  47. await user.destroyCascade(); // destroy model + children (useful for foreign keys)

  49. /* ModelArray methods */
  50. users.setAll('username', 'instant');
  51. users.readAll({username: 'instant'});
  52. await users.saveAll();
  53. await users.destroyAll();
  54. await users.destroyCascade();
  55. ```

Vector fields


instant.dev comes with built-in support for pgvector and the
vector field type. For full instructions on using vectors please check out the
Instant ORM: Vector fields documentation.

Set a vector engine via a plugin (OpenAI is the default):

File _instant/plugins/000_set_vector_engine.mjs:

  1. ```javascript
  2. import OpenAI from 'openai';
  3. const openai = new OpenAI({apiKey: process.env.OPENAI_API_KEY});

  5. export const plugin = async (Instant) => {
  6.   Instant.Vectors.setEngine(async (values) => {
  7.     const embedding = await openai.embeddings.create({
  8.       model: 'text-embedding-ada-002',
  9.       input: values
  10.     });
  11.     return embedding.data.map(entry => entry.embedding);
  12.   });
  13. };
  14. ```

Explain how we want to automatically store vector fields:

File: _instant/models/blog_post.mjs

  1. ```javascript
  2. import InstantORM from '@instant.dev/orm';

  4. class BlogPost extends InstantORM.Core.Model {

  6.   static tableName = 'blog_posts';

  8. }

  10. // Stores the `title` and `content` fields together as a vector
  11. // in the `content_embedding` vector field
  12. BlogPost.vectorizes(
  13.   'content_embedding',
  14.   (title, content) => `Title: ${title}\n\nBody: ${content}`
  15. );
  16. // optional, just prevents .toJSON() printing the entire array
  17. BlogPost.hides('content_embedding');

  19. export default BlogPost;
  20. ```

And query our vector fields:

  1. ```javascript
  2. const blogPost = await BlogPost.create({title: `My first post`, content: `some content`});
  3. const vector = blogPost.get('content_embedding'); // length 1,536 array

  5. // Find the top 10 blog posts matching "blog posts about dogs"
  6. // Automatically converts query to a vector
  7. let searchBlogPosts = await BlogPost.query()
  8.   .search('content_embedding', 'blog posts about dogs')
  9.   .limit(10)
  10.   .select();
  11. ```

You can read more on vector queries at
Composer#search and Composer#similarity.

Query composition


  1. ```javascript
  2. const User = Instant.Model('User');

  4. // Basic querying
  5. let users = await User.query()
  6.   .where({id__in: [7, 8, 9]})
  7.   .orderBy('username', 'ASC')
  8.   .limit(2)
  9.   .select();

  11. // Query with OR by sending in a list of where objects
  12. users = await User.query()
  13.   .where( // Can pass in arguments or an array
  14.     {id__in: [7, 8, 9]},
  15.     {username__istartswith: 'Rom'}
  16.   )
  17.   .select();

  19. // evaluate custom values with SQL commands
  20. // in this case, get users where their username matches the first part of their
  21. // email address
  22. users = await User.query()
  23.   .where({
  24.     username: email => `SPLIT_PART(${email}, '@', 1)`
  25.   })
  26.   .select();

  28. // Joins
  29. users = await User.query()
  30.   .join('posts', {title__icontains: 'hello'}) // JOIN ON
  31.   .where({
  32.     username: 'fred',
  33.     posts__like_count__gt: 5 // query joined table
  34.   })
  35.   .select();
  36. users.forEach(user => {
  37.   let posts = user.joined('posts');
  38.   console.log(posts.toJSON()); // log all posts
  39. });

  41. // Deeply-nested joins:
  42. // only get users who have followers that have posts with images from imgur
  43. users = await User.query()
  44.   .join('followers__posts__images')
  45.   .where({followers__posts__images__url__contains: 'imgur.com'})
  46.   .select();
  47. // Access user[0].followers[0].posts[0].images[0] with...
  48. users[0].joined('followers')[0].joined('posts')[0].joined('images')[0];

  50. // Queries are immutable and composable
  51. // Each command creates a new query object from the previous one
  52. let query = User.query();
  53. let query2 = query.where({username__istartswith: 'Rom'});
  54. let query3 = query2.orderBy('username', 'ASC');
  55. let allUsers = await query.select();
  56. let romUsers = await query2.select();
  57. let orderedUsers = await query3.select();

  59. // You can also just query raw SQL!
  60. await Instant.database().query(`SELECT * FROM users`);
  61. ```

Transactions


  1. ```javascript
  2. const User = Instant.Model('User');
  3. const Account = Instant.Model('Account');

  5. const txn = Instant.database().createTransaction();

  7. const user = await User.create({email: 'keith@instant.dev'}, txn);
  8. const account = await Account.create({user_id: user.get('id')}, txn);
  9. await txn.commit(); // commit queries to database
  10. // OR...
  11. await txn.rollback(); // if anything went wrong, rollback nullifies the queries

  13. // Can pass transactions to the following Class methods
  14. await Model.find(id, txn);
  15. await Model.findBy(field, value, txn);
  16. await Model.create(data, txn);
  17. await Model.update(id, data, txn);
  18. await Model.updateOrCreateBy(field, data, txn);
  19. await Model.query().count(txn);
  20. await Model.query().first(txn);
  21. await Model.query().select(txn);
  22. await Model.query().update(fields, txn);
  23. // Instance methods
  24. await model.save(txn);
  25. await model.destroy(txn);
  26. await model.destroyCascade(txn);
  27. // Instance Array methods
  28. await modelArray.saveAll(txn);
  29. await modelArray.destroyAll(txn);
  30. await modelArray.destroyCascade(txn);
  31. ```

Input validation


File: _instant/models/user.mjs

  1. ```javascript
  2. import InstantORM from '@instant.dev/orm';

  4. class User extends InstantORM.Core.Model {

  6.   static tableName = 'users';

  8. }

  10. // Validates email and password before .save()
  11. User.validates(
  12.   'email',
  13.   'must be valid',
  14.   v => v && (v + '').match(/.+@.+\.\w+/i)
  15. );
  16. User.validates(
  17.   'password',
  18.   'must be at least 5 characters in length',
  19.   v => v && v.length >= 5
  20. );

  22. export default User;
  23. ```

Now validations can be used;

  1. ```javascript
  2. const User = Instant.Model('User');

  4. try {
  5.   await User.create({email: 'invalid'});
  6. } catch (e) {
  7.   // Will catch a validation error
  8.   console.log(e.details);
  9.   /*
  10.     {
  11.       "email": ["must be valid"],
  12.       "password": ["must be at least 5 characters in length"]
  13.     }
  14.   */
  15. }
  16. ```

Relationship verification


File: _instant/models/user.mjs

  1. ```javascript
  2. import InstantORM from '@instant.dev/orm';

  4. class User extends InstantORM.Core.Model {

  6.   static tableName = 'users';

  8. }

  10. // Before saving to the database, asynchronously compare fields to each other
  11. User.verifies(
  12.   'phone_number',
  13.   'must correspond to country and be valid',
  14.   async (phone_number, country) => {
  15.     let phoneResult = await someAsyncPhoneValidationAPI(phone_number);
  16.     return (phoneResult.valid === true && phoneResult.country === country);
  17.   }
  18. );

  20. export default User;
  21. ```