BubbleORM

A Prisma-like ORM for Bubble.io applications using the Bubble Data API.

Features

• 🔄 Automatic schema generation from Bubble.io metadata
• 🧩 Type-safe models with TypeScript interfaces
• 🔍 Intuitive API for querying, creating, updating, and deleting data
• 🚀 Easy setup with CLI commands
• 🔐 Simple authentication with Bubble API key

Installation

npm install bubbleorm

Quick Start

1. Set up environment variables

Create a .env file in your project root with the following:

BUBBLE_APP_URL=https://yourapp.bubbleapps.io/version-test/api/1.1/obj
BUBBLE_API_KEY=your-api-key-here

2. Generate schema from your Bubble.io app

npx bubbleorm schema

This will:

• Fetch metadata from your Bubble.io app
• Generate a schema file (bubble-schema.json)
• Create TypeScript interfaces for your data types
• Generate model classes for interacting with your data

3. Use in your application

import * as dotenv from 'dotenv';
import { BubbleORMClient } from './models';

// Load environment variables
dotenv.config();

async function main() {
  // Create a client
  const bubbleORM = new BubbleORMClient({
    appUrl: process.env.BUBBLE_APP_URL!,
    apiKey: process.env.BUBBLE_API_KEY!,
  });

  try {
    // Find all users
    const users = await bubbleORM.user.findAll();
    console.log('All users:', users);

    // Find user by ID
    const user = await bubbleORM.user.findById('1234567890');
    console.log('User by ID:', user);

    // Create a new user
    const newUser = await bubbleORM.user.create({
      name: 'John Doe',
      email: '[email protected]',
    });
    console.log('New user:', newUser);

    // Update a user
    const updatedUser = await bubbleORM.user.update('1234567890', {
      name: 'Jane Doe',
    });
    console.log('Updated user:', updatedUser);

    // Delete a user
    await bubbleORM.user.delete('1234567890');
    console.log('User deleted');
  } catch (error) {
    console.error('Error:', error);
  }
}

main().catch(console.error);

API Reference

Finding Records

// Find all records
const users = await bubbleORM.user.findAll();

// Find with constraints
const users = await bubbleORM.user.findAll({
  constraints: [
    {
      key: 'name1_text',
      constraint_type: 'contains',
      value: 'John',
    },
  ],
  limit: 10,
  sort_field: 'Created Date',
  ascending: false,
});

// Find by ID
const user = await bubbleORM.user.findById('1234567890');

// Find first matching record
const user = await bubbleORM.user.findFirst({
  constraints: [
    {
      key: 'email',
      constraint_type: 'equals',
      value: '[email protected]',
    },
  ],
});

// Count records
const count = await bubbleORM.user.count();

Creating Records

const newUser = await bubbleORM.user.create({
  name1_text: 'John Doe',
  email: '[email protected]',
});

Updating Records

const updatedUser = await bubbleORM.user.update('1234567890', {
  name1_text: 'Jane Doe',
});

Deleting Records

await bubbleORM.user.delete('1234567890');

Constraint Types

BubbleORM supports the following constraint types:

• equals
• not equal
• greater than
• less than
• is empty
• is not empty
• contains
• not contains
• geographic_search

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.