Describe - AI-Powered API Library

npm package - https://www.npmjs.com/package/@describejs/core

DescribeJS lets you build complete APIs with single route per table in database and lets you call the api endpoints in plain english

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!