drizzle-cube 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,322 @@
+# 🐲 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, eq } from 'drizzle-cube/server'
+import { schema } from './schema'
+
+export const employeesCube = defineCube(schema, {
+  name: 'Employees',
+  
+  // Use Drizzle query builder for type safety
+  sql: ({ db, securityContext }) => 
+    db.select()
+      .from(schema.employees)
+      .leftJoin(schema.departments, eq(schema.employees.departmentId, schema.departments.id))
+      .where(eq(schema.employees.organisationId, securityContext.organisationId)),
+  
+  dimensions: {
+    name: { sql: schema.employees.name, type: 'string' },
+    email: { sql: schema.employees.email, type: 'string' },
+    departmentName: { sql: schema.departments.name, type: 'string' }
+  },
+  
+  measures: {
+    count: { sql: schema.employees.id, type: 'count' },
+    totalSalary: { sql: schema.employees.salary, type: 'sum', format: 'currency' },
+    avgSalary: { 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'
+
+// Setup Drizzle
+const client = postgres(process.env.DATABASE_URL!)
+const db = drizzle(client, { schema })
+
+// Create semantic layer
+const semanticLayer = new SemanticLayerCompiler({ drizzle: db, schema })
+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(schema, {
+  dimensions: {
+    name: { sql: schema.employees.name },        // ✅ Type-safe
+    invalid: { sql: schema.employees.invalidCol } // ❌ TypeScript error
+  }
+})
+```
+
+### ⚡ 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
+const advancedCube = defineCube(schema, {
+  name: 'DepartmentAnalytics',
+  
+  sql: ({ db, securityContext }) => 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 = ${securityContext.organisationId}
+      GROUP BY d.id, d.name
+    )
+    SELECT * FROM department_stats
+  `,
+  
+  dimensions: {
+    name: { sql: sql`name`, type: 'string' }
+  },
+  
+  measures: {
+    employeeCount: { sql: sql`employee_count`, type: 'number' },
+    avgSalary: { sql: sql`avg_salary`, type: 'number', format: 'currency' }
+  }
+})
+```
+
+### Advanced Security with Row-Level Security
+
+```typescript
+const secureCube = defineCube(schema, {
+  name: 'SecureEmployees',
+  
+  sql: ({ db, securityContext }) => 
+    db.select()
+      .from(schema.employees)
+      .where(
+        and(
+          eq(schema.employees.organisationId, securityContext.organisationId),
+          // Only show employees user has permission to see
+          securityContext.role === 'admin' 
+            ? sql`true`
+            : eq(schema.employees.managerId, securityContext.userId)
+        )
+      )
+})
+```
+
+### 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(schema, definition)` - Create type-safe cube
+- `createSemanticLayer({ drizzle, schema })` - Setup semantic layer
+- `createCubeApp(options)` - Create Cube.js 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
+
+📚 **[Complete Documentation](https://drizzle-cube.dev)**  
+🏗️ **[API Reference](https://drizzle-cube.dev/api)**  
+🎯 **[Drizzle Integration Guide](./docs/drizzle-integration.md)**  
+🚀 **[Migration Guide](https://drizzle-cube.dev/migration)**  
+
+## Examples
+
+- **[Basic Hono App](./examples/hono-basic/)**
+- **[Advanced Security](./examples/hono-security/)**
+- **[Multi-tenant SaaS](./examples/multi-tenant/)**
+- **[Real-time Dashboard](./examples/dashboard/)**
+
+## 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;
+}