drizzle-cube 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,407 @@
+# 🐲 Drizzle Cube
+
+**Drizzle ORM-first semantic layer with Cube.js compatibility**
+
+Transform your Drizzle schema into a powerful, type-safe analytics platform with SQL injection protection and full TypeScript support.
+
+[![NPM Version](https://img.shields.io/npm/v/drizzle-cube)](https://www.npmjs.com/package/drizzle-cube)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
+[![Drizzle ORM](https://img.shields.io/badge/Drizzle%20ORM-0.33+-green)](https://orm.drizzle.team/)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+
+## Why Drizzle Cube?
+
+🔒 **SQL Injection Proof** - All queries use Drizzle's parameterized SQL  
+🛡️ **Type Safe** - Full TypeScript inference from your database schema  
+⚡ **Performance** - Prepared statements and query optimization  
+🧩 **Cube.js Compatible** - Works with existing Cube.js React components  
+🎯 **Zero Config** - Infer cube definitions from your Drizzle schema  
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install drizzle-cube drizzle-orm
+```
+
+### 2. Define Your Schema
+
+```typescript
+// schema.ts
+import { pgTable, text, integer, boolean } from 'drizzle-orm/pg-core'
+
+export const employees = pgTable('employees', {
+  id: integer('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email'),
+  active: boolean('active').default(true),
+  departmentId: integer('department_id'),
+  organisationId: integer('organisation_id').notNull(),
+  salary: integer('salary')
+})
+
+export const departments = pgTable('departments', {
+  id: integer('id').primaryKey(),
+  name: text('name').notNull(),
+  organisationId: integer('organisation_id').notNull()
+})
+
+export const schema = { employees, departments }
+```
+
+### 3. Create Type-Safe Cubes
+
+```typescript
+// cubes.ts
+import { defineCube } from 'drizzle-cube/server'
+import { eq } from 'drizzle-orm'
+import { schema } from './schema'
+
+export const employeesCube = defineCube('Employees', {
+  title: 'Employee Analytics',
+  
+  // Use Drizzle query structure for type safety
+  sql: (ctx) => ({
+    from: schema.employees,
+    joins: [
+      {
+        table: schema.departments,
+        on: eq(schema.employees.departmentId, schema.departments.id),
+        type: 'left'
+      }
+    ],
+    where: eq(schema.employees.organisationId, ctx.securityContext.organisationId)
+  }),
+  
+  dimensions: {
+    name: {
+      name: 'name',
+      title: 'Employee Name',
+      sql: schema.employees.name,
+      type: 'string'
+    },
+    email: {
+      name: 'email', 
+      title: 'Email Address',
+      sql: schema.employees.email,
+      type: 'string'
+    },
+    departmentName: {
+      name: 'departmentName',
+      title: 'Department',
+      sql: schema.departments.name,
+      type: 'string'
+    }
+  },
+  
+  measures: {
+    count: {
+      name: 'count',
+      title: 'Total Employees',
+      sql: schema.employees.id,
+      type: 'count'
+    },
+    totalSalary: {
+      name: 'totalSalary',
+      title: 'Total Salary',
+      sql: schema.employees.salary,
+      type: 'sum',
+      format: 'currency'
+    },
+    avgSalary: {
+      name: 'avgSalary',
+      title: 'Average Salary', 
+      sql: schema.employees.salary,
+      type: 'avg',
+      format: 'currency'
+    }
+  }
+})
+```
+
+### 4. Setup API Server
+
+```typescript
+// server.ts
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { createCubeApp } from 'drizzle-cube/adapters/hono'
+import { SemanticLayerCompiler } from 'drizzle-cube/server'
+import postgres from 'postgres'
+import { schema } from './schema'
+import { employeesCube } from './cubes'
+
+// Setup Drizzle
+const client = postgres(process.env.DATABASE_URL!)
+const db = drizzle(client, { schema })
+
+// Create semantic layer
+const semanticLayer = new SemanticLayerCompiler({
+  drizzle: db,
+  schema,
+  engineType: 'postgres'
+})
+semanticLayer.registerCube(employeesCube)
+
+// Create API server with Cube.js compatibility
+const app = createCubeApp({
+  semanticLayer,
+  drizzle: db,
+  schema,
+  getSecurityContext: async (c) => ({
+    organisationId: c.get('user')?.organisationId
+  })
+})
+
+export default app
+```
+
+### 5. Query from Frontend
+
+```typescript
+// Use with Cube.js React SDK
+import { useCubeQuery } from '@cubejs-client/react'
+
+function EmployeeStats() {
+  const { resultSet, isLoading } = useCubeQuery({
+    measures: ['Employees.count', 'Employees.avgSalary'],
+    dimensions: ['Employees.departmentName'],
+    filters: [
+      { member: 'Employees.active', operator: 'equals', values: [true] }
+    ]
+  })
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <table>
+      {resultSet.tablePivot().map((row, i) => (
+        <tr key={i}>
+          <td>{row['Employees.departmentName']}</td>
+          <td>{row['Employees.count']}</td>
+          <td>${row['Employees.avgSalary']}</td>
+        </tr>
+      ))}
+    </table>
+  )
+}
+```
+
+## Key Features
+
+### 🔐 Security First
+
+All SQL is generated using Drizzle's parameterized queries, making SQL injection impossible:
+
+```typescript
+// ❌ Vulnerable (string concatenation)
+const sql = `WHERE name = '${userInput}'`
+
+// ✅ Safe (Drizzle parameterization)  
+const condition = eq(schema.employees.name, userInput)
+```
+
+### 🏗️ Type Safety
+
+Get full TypeScript support from your database schema to your analytics:
+
+```typescript
+const cube = defineCube('Employees', {
+  dimensions: {
+    name: {
+      name: 'name',
+      title: 'Employee Name',
+      sql: schema.employees.name,        // ✅ Type-safe
+      type: 'string'
+    },
+    invalid: {
+      name: 'invalid',
+      sql: schema.employees.invalidCol,  // ❌ TypeScript error
+      type: 'string'
+    }
+  }
+})
+```
+
+### ⚡ Performance
+
+- **Prepared Statements**: Drizzle generates optimized prepared statements
+- **Query Planning**: Database optimizes repeated queries automatically  
+- **Connection Pooling**: Leverages Drizzle's connection management
+
+### 🧩 Framework Support
+
+Works with multiple frameworks via adapter pattern:
+
+- **Hono** - Built-in adapter
+- **Express** - Coming soon
+- **Fastify** - Coming soon
+- **Next.js** - Coming soon
+
+## Advanced Usage
+
+### Complex Queries with CTEs
+
+```typescript
+import { sql } from 'drizzle-orm'
+
+const advancedCube = defineCube('DepartmentAnalytics', {
+  title: 'Department Analytics',
+  
+  // For complex queries, you can use raw SQL
+  sql: (ctx) => sql`
+    WITH department_stats AS (
+      SELECT 
+        d.id,
+        d.name,
+        COUNT(e.id) as employee_count,
+        AVG(e.salary) as avg_salary
+      FROM ${schema.departments} d
+      LEFT JOIN ${schema.employees} e ON d.id = e.department_id
+      WHERE d.organisation_id = ${ctx.securityContext.organisationId}
+      GROUP BY d.id, d.name
+    )
+    SELECT * FROM department_stats
+  `,
+  
+  dimensions: {
+    name: {
+      name: 'name',
+      title: 'Department Name',
+      sql: sql`name`,
+      type: 'string'
+    }
+  },
+  
+  measures: {
+    employeeCount: {
+      name: 'employeeCount',
+      title: 'Employee Count',
+      sql: sql`employee_count`,
+      type: 'number'
+    },
+    avgSalary: {
+      name: 'avgSalary',
+      title: 'Average Salary',
+      sql: sql`avg_salary`,
+      type: 'number',
+      format: 'currency'
+    }
+  }
+})
+```
+
+### Advanced Security with Row-Level Security
+
+```typescript
+import { and, sql } from 'drizzle-orm'
+
+const secureCube = defineCube('SecureEmployees', {
+  title: 'Secure Employee Data',
+  
+  sql: (ctx) => ({
+    from: schema.employees,
+    where: and(
+      eq(schema.employees.organisationId, ctx.securityContext.organisationId),
+      // Only show employees user has permission to see
+      ctx.securityContext.role === 'admin' 
+        ? sql`true`
+        : eq(schema.employees.managerId, ctx.securityContext.userId)
+    )
+  }),
+  
+  dimensions: {
+    name: {
+      name: 'name',
+      title: 'Employee Name',
+      sql: schema.employees.name,
+      type: 'string'
+    }
+  },
+  
+  measures: {
+    count: {
+      name: 'count',
+      title: 'Employee Count',
+      sql: schema.employees.id,
+      type: 'count'
+    }
+  }
+})
+```
+
+### Multiple Database Support
+
+```typescript
+// PostgreSQL
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+
+// MySQL  
+import { drizzle } from 'drizzle-orm/mysql2'
+import mysql from 'mysql2/promise'
+
+// SQLite
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import Database from 'better-sqlite3'
+```
+
+## API Reference
+
+### Core Functions
+
+- `defineCube(name, definition)` - Create type-safe cube with name and configuration
+- `SemanticLayerCompiler({ drizzle, schema, engineType })` - Setup semantic layer compiler
+- `createCubeApp(options)` - Create Cube.js-compatible API server
+
+### Supported Drizzle Features
+
+- ✅ **All Database Types** - PostgreSQL, MySQL, SQLite
+- ✅ **Query Builder** - Full Drizzle query builder support
+- ✅ **Schema References** - Direct column references
+- ✅ **SQL Templates** - Raw SQL with parameterization
+- ✅ **Aggregations** - count, sum, avg, min, max, countDistinct
+- ✅ **Joins** - Inner, left, right, full outer joins
+- ✅ **CTEs** - Common table expressions
+- ✅ **Subqueries** - Nested query support
+- ✅ **Window Functions** - Advanced analytics
+- ✅ **JSON Operations** - PostgreSQL JSON/JSONB support
+
+### Filter Operators
+
+Supports all Cube.js filter operators with Drizzle safety:
+
+- `equals`, `notEquals` → `eq()`, `ne()`
+- `contains`, `notContains` → `ilike()`, `notIlike()`  
+- `gt`, `gte`, `lt`, `lte` → `gt()`, `gte()`, `lt()`, `lte()`
+- `set`, `notSet` → `isNotNull()`, `isNull()`
+- `inDateRange` → `and(gte(), lte())`
+
+## Documentation
+
+Coming soon! 📚
+
+## Examples
+
+Coming soon! Check the test files for usage patterns in the meantime.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md).
+
+## Roadmap
+
+- 🔄 **Express Adapter** - Express.js integration
+- 🔄 **Fastify Adapter** - Fastify integration  
+- 🔄 **Next.js Adapter** - Next.js API routes
+- 🔄 **Pre-aggregations** - Materialized view support
+- 🔄 **Real-time Updates** - WebSocket support
+- 🔄 **Query Caching** - Redis integration
+
+## License
+
+MIT © [Clifton Cunningham](https://github.com/cliftonc)
+
+---
+
+**Built with ❤️ for the Drizzle ORM community**

package/dist/adapters/hono/index.d.ts

@@ -0,0 +1,49 @@
+import { Hono } from 'hono';
+import { SemanticLayerCompiler, SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase } from '../../server';
+export interface HonoAdapterOptions<TSchema extends Record<string, any> = Record<string, any>> {
+    /**
+     * The semantic layer instance to use
+     */
+    semanticLayer: SemanticLayerCompiler<TSchema>;
+    /**
+     * Drizzle database instance (REQUIRED)
+     * This is the core of drizzle-cube - Drizzle ORM integration
+     */
+    drizzle: DrizzleDatabase<TSchema>;
+    /**
+     * Database schema for type inference (RECOMMENDED)
+     * Provides full type safety for cube definitions
+     */
+    schema?: TSchema;
+    /**
+     * Function to extract security context from Hono context
+     * This is where you provide your app-specific context extraction logic
+     */
+    getSecurityContext: (c: any) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * CORS configuration (optional)
+     */
+    cors?: {
+        origin?: string | string[] | ((origin: string, c: any) => string | null | undefined);
+        allowMethods?: string[];
+        allowHeaders?: string[];
+        credentials?: boolean;
+    };
+    /**
+     * API base path (default: '/cubejs-api/v1')
+     */
+    basePath?: string;
+}
+/**
+ * Create Hono routes for Cube.js-compatible API
+ */
+export declare function createCubeRoutes<TSchema extends Record<string, any> = Record<string, any>>(options: HonoAdapterOptions<TSchema>): Hono<import('hono/types').BlankEnv, import('hono/types').BlankSchema, "/">;
+/**
+ * Convenience function to create routes and mount them on an existing Hono app
+ */
+export declare function mountCubeRoutes<TSchema extends Record<string, any> = Record<string, any>>(app: Hono, options: HonoAdapterOptions<TSchema>): Hono<import('hono/types').BlankEnv, import('hono/types').BlankSchema, "/">;
+/**
+ * Create a complete Hono app with Cube.js routes
+ */
+export declare function createCubeApp<TSchema extends Record<string, any> = Record<string, any>>(options: HonoAdapterOptions<TSchema>): Hono<import('hono/types').BlankEnv, import('hono/types').BlankSchema, "/">;
+export type { SecurityContext, DatabaseExecutor, SemanticQuery, DrizzleDatabase };

package/dist/adapters/hono/index.js

@@ -1,5 +1,172 @@
-function o() {
+import { Hono as w } from "hono";
+var j = (f) => {
+  const u = {
+    ...{
+      origin: "*",
+      allowMethods: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH"],
+      allowHeaders: [],
+      exposeHeaders: []
+    },
+    ...f
+  }, q = /* @__PURE__ */ ((a) => typeof a == "string" ? a === "*" ? () => a : (t) => a === t ? t : null : typeof a == "function" ? a : (t) => a.includes(t) ? t : null)(u.origin), m = ((a) => typeof a == "function" ? a : Array.isArray(a) ? () => a : () => [])(u.allowMethods);
+  return async function(t, d) {
+    var i;
+    function e(r, n) {
+      t.res.headers.set(r, n);
+    }
+    const o = q(t.req.header("origin") || "", t);
+    if (o && e("Access-Control-Allow-Origin", o), u.origin !== "*") {
+      const r = t.req.header("Vary");
+      r ? e("Vary", r) : e("Vary", "Origin");
+    }
+    if (u.credentials && e("Access-Control-Allow-Credentials", "true"), (i = u.exposeHeaders) != null && i.length && e("Access-Control-Expose-Headers", u.exposeHeaders.join(",")), t.req.method === "OPTIONS") {
+      u.maxAge != null && e("Access-Control-Max-Age", u.maxAge.toString());
+      const r = m(t.req.header("origin") || "", t);
+      r.length && e("Access-Control-Allow-Methods", r.join(","));
+      let n = u.allowHeaders;
+      if (!(n != null && n.length)) {
+        const s = t.req.header("Access-Control-Request-Headers");
+        s && (n = s.split(/\s*,\s*/));
+      }
+      return n != null && n.length && (e("Access-Control-Allow-Headers", n.join(",")), t.res.headers.append("Vary", "Access-Control-Request-Headers")), t.res.headers.delete("Content-Length"), t.res.headers.delete("Content-Type"), new Response(null, {
+        headers: t.res.headers,
+        status: 204,
+        statusText: "No Content"
+      });
+    }
+    await d();
+  };
+};
+function C(f) {
+  const {
+    semanticLayer: l,
+    drizzle: u,
+    schema: q,
+    getSecurityContext: m,
+    cors: a,
+    basePath: t = "/cubejs-api/v1"
+  } = f, d = new w();
+  return a && d.use("/*", j(a)), l.hasExecutor() || l.setDrizzle(u, q), d.post(`${t}/load`, async (e) => {
+    var o, i;
+    try {
+      const r = await e.req.json(), n = await m(e);
+      if (!((o = r.measures) != null && o.length) && !((i = r.dimensions) != null && i.length))
+        return e.json({
+          error: "Query must specify at least one measure or dimension"
+        }, 400);
+      const s = await l.executeMultiCubeQuery(r, n);
+      return e.json({
+        data: s.data,
+        annotation: s.annotation,
+        query: r,
+        slowQuery: !1
+      });
+    } catch (r) {
+      return console.error("Query execution error:", r), e.json({
+        error: r instanceof Error ? r.message : "Query execution failed"
+      }, 500);
+    }
+  }), d.get(`${t}/load`, async (e) => {
+    var o, i;
+    try {
+      const r = e.req.query("query");
+      if (!r)
+        return e.json({
+          error: "Query parameter is required"
+        }, 400);
+      const n = JSON.parse(r), s = await m(e);
+      if (!((o = n.measures) != null && o.length) && !((i = n.dimensions) != null && i.length))
+        return e.json({
+          error: "Query must specify at least one measure or dimension"
+        }, 400);
+      const c = await l.executeMultiCubeQuery(n, s);
+      return e.json({
+        data: c.data,
+        annotation: c.annotation,
+        query: n,
+        slowQuery: !1
+      });
+    } catch (r) {
+      return console.error("Query execution error:", r), e.json({
+        error: r instanceof Error ? r.message : "Query execution failed"
+      }, 500);
+    }
+  }), d.get(`${t}/meta`, async (e) => {
+    try {
+      const o = l.getMetadata();
+      return e.json({
+        cubes: o
+      });
+    } catch (o) {
+      return console.error("Metadata error:", o), e.json({
+        error: o instanceof Error ? o.message : "Failed to fetch metadata"
+      }, 500);
+    }
+  }), d.post(`${t}/sql`, async (e) => {
+    var o, i, r, n;
+    try {
+      const s = await e.req.json(), c = await m(e);
+      if (!((o = s.measures) != null && o.length) && !((i = s.dimensions) != null && i.length))
+        return e.json({
+          error: "Query must specify at least one measure or dimension"
+        }, 400);
+      const y = ((r = s.measures) == null ? void 0 : r[0]) || ((n = s.dimensions) == null ? void 0 : n[0]);
+      if (!y)
+        return e.json({
+          error: "No measures or dimensions specified"
+        }, 400);
+      const g = y.split(".")[0], h = await l.generateSQL(g, s, c);
+      return e.json({
+        sql: h.sql,
+        params: h.params || [],
+        query: s
+      });
+    } catch (s) {
+      return console.error("SQL generation error:", s), e.json({
+        error: s instanceof Error ? s.message : "SQL generation failed"
+      }, 500);
+    }
+  }), d.get(`${t}/sql`, async (e) => {
+    var o, i, r, n;
+    try {
+      const s = e.req.query("query");
+      if (!s)
+        return e.json({
+          error: "Query parameter is required"
+        }, 400);
+      const c = JSON.parse(s), y = await m(e);
+      if (!((o = c.measures) != null && o.length) && !((i = c.dimensions) != null && i.length))
+        return e.json({
+          error: "Query must specify at least one measure or dimension"
+        }, 400);
+      const g = ((r = c.measures) == null ? void 0 : r[0]) || ((n = c.dimensions) == null ? void 0 : n[0]);
+      if (!g)
+        return e.json({
+          error: "No measures or dimensions specified"
+        }, 400);
+      const h = g.split(".")[0], p = await l.generateSQL(h, c, y);
+      return e.json({
+        sql: p.sql,
+        params: p.params || [],
+        query: c
+      });
+    } catch (s) {
+      return console.error("SQL generation error:", s), e.json({
+        error: s instanceof Error ? s.message : "SQL generation failed"
+      }, 500);
+    }
+  }), d;
+}
+function x(f, l) {
+  const u = C(l);
+  return f.route("/", u), f;
+}
+function A(f) {
+  const l = new w();
+  return x(l, f);
 }
 export {
-  o as createHonoRoutes
+  A as createCubeApp,
+  C as createCubeRoutes,
+  x as mountCubeRoutes
 };

package/dist/adapters/types.d.ts

@@ -0,0 +1,41 @@
+import { SemanticLayerCompiler, SecurityContext, DatabaseExecutor } from '../server';
+/**
+ * Base adapter configuration
+ */
+export interface BaseAdapterOptions {
+    semanticLayer: SemanticLayerCompiler;
+    databaseExecutor?: DatabaseExecutor;
+    basePath?: string;
+}
+/**
+ * Framework-specific context extractor
+ * Each framework adapter will provide their own context type
+ */
+export interface ContextExtractor<TContext = any> {
+    (context: TContext): SecurityContext | Promise<SecurityContext>;
+}
+/**
+ * Standard CORS configuration
+ */
+export interface CorsConfig {
+    origin?: string | string[] | ((origin: string) => boolean);
+    allowMethods?: string[];
+    allowHeaders?: string[];
+    credentials?: boolean;
+}
+/**
+ * Standard adapter response format
+ */
+export interface AdapterResponse {
+    data?: any;
+    error?: string;
+    status?: number;
+}
+/**
+ * Future adapter interface (for Express, Fastify, etc.)
+ */
+export interface AdapterFactory<TOptions extends BaseAdapterOptions, TApp = any> {
+    createRoutes(options: TOptions): TApp;
+    mountRoutes?(app: TApp, options: TOptions): TApp;
+    createApp?(options: TOptions): TApp;
+}