Describe - AI-Powered API Library

DescribeJS lets you build complete APIs by describing what you want in plain English. No more boilerplate, just define your schema and tell the system what to do.

Describe your intent → Get an API route instantly.

🚀 Features

• Natural Language Endpoints – Write route descriptions instead of REST logic

• Multi-Database Support – MongoDB, PostgreSQL, MySQL, Redis

• Schema-Driven – Define once, use everywhere

• Automatic Validation – Built-in data type and rule checking

• AI-Powered Intent Detection – Maps natural language to CRUD operations

• Route-Based Architecture – Each route corresponds to a table/entity

📦 Installation

Core Package

npm install @describe/core

Database Adapters (Choose what you need)

NoSQL Databases

npm install @describe/db-mongodb
npm install @describe/db-redis

SQL Databases

npm install @describe/db-postgresql
npm install @describe/db-mysql

🎯 Quick Start

import app from '@describe/core';
import mongodbAdapter from '@describe/db-mongodb';

// Register database adapter
app.useDB('mongodb', mongodbAdapter);

// Connect to database
await app.connectDB('mongodb', {
  uri: 'mongodb://localhost:27017/myapp'
});

// Define routes with schemas
const user = app.route('/user', {
  username: 'string',
  email: 'string',
  age: 'number'
}, (data) => {
  // Optional validation function
  if (data.age < 18) throw new Error('Must be 18+');
});

// Start server
app.listen(3000);

🔥 Usage Examples

API Calls

All operations go through POST /{route}/query endpoints:

Create a User

POST http://localhost:3000/user/query
{
  "query": "create a new user",
  "body": {
    "username": "john",
    "email": "[email protected]",
    "age": 25
  }
}

Get User by Username

POST http://localhost:3000/user/query
{
  "query": "get user by username",
  "body": {
    "username": "john"
  }
}

Update User Email

POST http://localhost:3000/user/query
{
  "query": "update user email",
  "body": {
    "username": "john",
    "email": "[email protected]"
  }
}

Delete User

POST http://localhost:3000/user/query
{
  "query": "delete user",
  "body": {
    "username": "john"
  }
}

Multiple Tables

// User table
const user = app.route('/user', {
  username: 'string',
  email: 'string',
  age: 'number'
});

// Orders table
const orders = app.route('/order', {
  userId: 'number',
  amount: 'number',
  status: 'string'
});

// Products table
const products = app.route('/product', {
  name: 'string',
  price: 'number',
  category: 'string'
});

Natural Language Queries

The AI understands various ways to express the same operation:

CREATE Operations:

• "create a new user"
• "add user"
• "register user"
• "insert user"

READ Operations:

• "get user by username"
• "find user"
• "search for user"
• "retrieve user data"

UPDATE Operations:

• "update user email"
• "modify user"
• "change user data"
• "edit user"

DELETE Operations:

• "delete user"
• "remove user"
• "destroy user account"

🗄️ Database Support

MongoDB

import mongodbAdapter from '@describe/db-mongodb';

app.useDB('mongodb', mongodbAdapter);
await app.connectDB('mongodb', {
  uri: 'mongodb://localhost:27017/myapp'
});

PostgreSQL

import postgresqlAdapter from '@describe/db-postgresql';

app.useDB('postgresql', postgresqlAdapter);
await app.connectDB('postgresql', {
  host: 'localhost',
  port: 5432,
  database: 'myapp',
  user: 'postgres',
  password: 'password'
});

MySQL

import mysqlAdapter from '@describe/db-mysql';

app.useDB('mysql', mysqlAdapter);
await app.connectDB('mysql', {
  host: 'localhost',
  port: 3306,
  database: 'myapp',
  user: 'root',
  password: 'password'
});

Redis

import redisAdapter from '@describe/db-redis';

app.useDB('redis', redisAdapter);
await app.connectDB('redis', {
  url: 'redis://localhost:6379'
});

🔧 Advanced Features

Custom Validation

const user = app.route('/user', {
  username: 'string',
  email: 'string',
  age: 'number'
}, (data) => {
  // Custom validation logic
  if (data.username.length < 3) {
    throw new Error('Username must be at least 3 characters');
  }
  if (!data.email.includes('@')) {
    throw new Error('Invalid email format');
  }
  if (data.age < 18) {
    throw new Error('Must be 18 or older');
  }
});

Schema Types

const product = app.route('/product', {
  name: 'string',        // String type
  price: 'number',       // Number type
  inStock: 'boolean',    // Boolean type
  tags: 'array',         // Array type
  metadata: 'object'     // Object type
});

Multiple Database Connections

// Connect to multiple databases
await app.connectDB('mongodb', { uri: 'mongodb://localhost:27017/users' });
await app.connectDB('postgresql', { 
  host: 'localhost', 
  database: 'orders',
  user: 'postgres',
  password: 'password'
});

📊 Response Format

All API responses follow this structure:

{
  "success": true,
  "operation": "CREATE",
  "confidence": 0.95,
  "message": "Record created successfully",
  "data": {
    "id": 123,
    "username": "john",
    "email": "[email protected]",
    "age": 25
  },
  "table": "user"
}

Error responses:

{
  "success": false,
  "error": "Validation failed",
  "details": ["Field 'age' must be a number, got string"],
  "table": "user"
}

🧪 Testing

Run the test suite:

node test.js

Run the example server:

node example.js

🏗️ Architecture

Route-Based Design

• Each route represents a database table/entity
• Routes are defined with schemas and optional validation
• Each route gets its own /query endpoint

AI Intent Detection

• Natural language processing maps queries to CRUD operations
• Keyword-based scoring system with confidence levels
• Extensible preset system for different operation types

Database Adapter Pattern

• Unified interface for different database types
• Automatic query generation based on database type
• Connection pooling and transaction support

Preset System

• Predefined templates for CREATE, READ, UPDATE, DELETE operations
• Database-specific query generation
• Customizable response messages

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

Made with ❤️ for developers who want to focus on business logic, not API boilerplate!