@barishnamazov/gsql 0.1.0 → 0.2.1

package/README.md

@@ -2,15 +2,103 @@
 
 **Parametric polymorphism for SQL schemas**
 
-GSQL is a domain-specific language that brings the power of generics/templates to database schemas. Define common patterns once, instantiate them anywhere.
+GSQL is a domain-specific language that brings the power of generics/templates to database schemas.
+Define common patterns once, instantiate them freely.
 
-## Features
+> Read the background story:
+> [Parametric Polymorphism for SQL](https://barish.me/blog/parametric-polymorphism-for-sql/)
 
+## The Problem
+
+When building relational databases, you often need to duplicate table structures with minor
+variations. For example, in a learning management system, you might need announcements for courses,
+lessons, and exams—the same pattern repeated three times.
+
+Current solutions force you to choose between:
+
+- **Separate tables** - Violates DRY principles, leads to maintenance nightmares
+- **Polymorphic associations** - Sacrifices foreign key integrity and type safety
+
+GSQL solves this by letting you define reusable schema templates (concepts) that compile to
+PostgreSQL with proper foreign key constraints.
+
+## Quick Example
+
+Here is the "LMS Dilemma" (Courses, Lessons, Exams) solved with GSQL. We define an `Announcing`
+pattern once and apply it to three different tables, generating strictly typed foreign keys for
+each.
+
+```
+// Define reusable patterns (Mixins)
+schema Timestamps {
+    created_at timestamptz nonull default(NOW());
+    updated_at timestamptz nonull default(NOW());
+}
+
+// Define a Generic Concept
+// Accepts a 'Target' type parameter to create a relationship
+concept Announcing<Target> {
+    schema Announcements mixin Timestamps {
+        id serial pkey;
+
+        // Template variables: {Target}_id becomes course_id, lesson_id, etc.
+        {Target}_id integer nonull ref(Target.id) ondelete(cascade);
+
+        title text nonull;
+        body text nonull;
+
+        index({Target}_id);
+    }
+}
+
+// Define Concrete Schemas (in actual app these would also be concepts with generics)
+schema Courses mixin Timestamps { id serial pkey; name text; }
+schema Lessons mixin Timestamps { id serial pkey; topic text; }
+schema Exams   mixin Timestamps { id serial pkey; score int; }
+
+// Actually create tables by instantiating the Schemas/Concepts
+courses = Courses;
+lessons = Lessons;
+exams   = Exams;
+
+// Create specific announcement tables for each entity
+course_announcements = Announcing<courses[course]>;
+lesson_announcements = Announcing<lessons[lesson]>;
+exam_announcements   = Announcing<exams[exam]>;
+
+// Add per-instance indexes if needed
+index(course_announcements, created_at);
+```
+
+This generates three announcement tables with proper foreign keys:
+
+```sql
+CREATE TABLE course_announcements (
+    id serial PRIMARY KEY,
+    course_id integer NOT NULL REFERENCES courses(id) ON DELETE CASCADE,
+    title text NOT NULL,
+    body text NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT NOW(),
+    updated_at timestamptz NOT NULL DEFAULT NOW()
+);
+CREATE INDEX ON course_announcements (course_id);
+--- ...
+```
+
+## Key Features
+
+- **Schemas**: A table definition with columns, constraints, indexes, triggers
 - **Concepts**: Generic schema templates with type parameters
 - **Mixins**: Compose reusable schema fragments
 - **Template variables**: Automatic field name expansion
+- **Sibling references**: Multiple schemas within one concept can reference each other
 - **Per-instance indexes**: Add indexes after instantiation
 - **Type-safe foreign keys**: Proper FK constraints for polymorphic patterns
+- **PostgreSQL output**: Compiles to PostgreSQL, integrates with migration tools like Atlas
+
+## Try It Out
+
+Try GSQL in your browser with the [online playground](https://gsql.barish.me).
 
 ## Installation
 
@@ -52,45 +140,6 @@ if (result.success) {
 const sql = compileToSQL(source);
 ```
 
-## Quick Example
-
-```gsql
-// Reusable timestamp pattern
-schema Timestamps {
-    created_at timestamptz nonull default(NOW());
-    updated_at timestamptz nonull default(NOW());
-}
-
-// Generic concept for announcements
-concept Announcing<Target> {
-    schema Announcements mixin Timestamps {
-        id serial pkey;
-        {Target}_id integer nonull ref(Target.id) ondelete(cascade);
-        message text nonull;
-
-        index({Target}_id);
-    }
-}
-
-// Concrete tables
-schema Posts {
-    id serial pkey;
-    title varchar(255);
-}
-
-posts = Posts;
-post_announcements = Announcing<posts[post]>;
-
-// Per-instance indexes
-index(post_announcements, created_at);
-```
-
-This generates proper SQL with:
-
-- A `posts` table
-- A `post_announcements` table with a `post_id` foreign key
-- Proper indexes and constraints
-
 ## Syntax Reference
 
 ### Schemas
@@ -107,16 +156,24 @@ schema Name mixin Mixin1, Mixin2 {
 ### Concepts
 
 ```gsql
-concept Name<TypeParam1, TypeParam2> {
-    enum status { active; inactive; }
+concept Tagging<Target> {
+    schema Tags {
+        id serial pkey;
+        name text;
+    }
 
-    schema Table {
-        {TypeParam1}_id integer ref(TypeParam1.id);
+    schema Taggings {
+        {Target}_id integer ref(Target.id);
+        {Tags}_id integer ref(Tags.id); // sibling reference
+        index({Target}_id, {Tags}_id) unique;
     }
 }
-```
 
-**Template Variables:** Use uppercase type parameter names in curly braces (e.g., `{Target}_id`, `{Author}_id`).
+users = Users;
+// {Target}_id becomes user_id
+// {Tags}_id becomes user_tag_id
+user_tags[user_tag], user_taggings = Tagging<users[user]>;
+```
 
 ### Instantiation
 
@@ -181,21 +238,44 @@ announcements = Announcing<exams[exam], authors>;
 
 ## Development
 
+This is a monorepo with multiple packages:
+
+- **`packages/gsql`** - Core library and CLI (published as `@barishnamazov/gsql`)
+- **`packages/playground`** - Browser-based playground
+
+### Building
+
 ```bash
-# Install dependencies
-npm install
+# Build everything
+npm run build
+
+# Build just the library
+npm run build:gsql
+
+# Build just the playground
+npm run build:playground
+```
+
+### Testing
 
-# Run tests
+```bash
 npm test
+```
 
-# Build
-npm run build
+### Playground Development
 
-# Lint
-npm run lint
+```bash
+npm run dev:playground
+```
+
+After building, open `packages/playground/dist/index.html` in your browser.
+
+### Linting and Formatting
 
-# Format
+```bash
+npm run lint
 npm run format
+npm run typecheck:all
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barishnamazov/gsql",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Generic SQL - Parametric Polymorphism for SQL Schemas",
   "module": "src/index.ts",
   "type": "module",
@@ -17,11 +17,14 @@
     "test:watch": "vitest",
     "lint": "eslint .",
     "format": "prettier --write --check \"src/**/*.ts\" \"test/**/*.ts\"",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "postversion": "git push && git push --tags"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/pg": "^8.11.10",
     "esbuild": "^0.25.12",
+    "pg": "^8.16.3",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },
@@ -39,7 +42,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/BarishNamazov/gsql-dev",
+    "url": "git+https://github.com/BarishNamazov/gsql.git",
     "directory": "packages/gsql"
   },
   "files": [

package/src/cli.ts

@@ -180,7 +180,7 @@ function main(): void {
   if (!result.success) {
     for (const error of result.errors) {
       console.error(
-        formatError(error.message, error.location?.start.line, error.location?.start.column)
+        formatError(error.message, error.location?.start.line, error.location?.start.column),
       );
     }
     process.exit(1);

package/src/generator.ts

@@ -47,6 +47,57 @@ function toSnakeCase(str: string): string {
     .toLowerCase();
 }
 
+/**
+ * Format a value with type casting for PostgreSQL.
+ * Converts type::value to 'value'::type format.
+ *
+ * Examples:
+ * - "status::active" -> "'active'::status"
+ * - "'active'::status" -> "'active'::status" (already formatted)
+ * - "42" -> "42" (no cast)
+ */
+function formatTypeCast(value: string): string {
+  // If no type cast operator, return as-is
+  if (!value.includes("::")) {
+    return value;
+  }
+
+  // Convert type::value to 'value'::type for any parts that need it
+  // This regex looks for word::word pattern and converts it
+  // Already formatted 'value'::type patterns are left unchanged
+  return value.replace(/(\w+)::(\w+)/g, "'$2'::$1");
+}
+
+/**
+ * Format an enum default value for PostgreSQL.
+ * Ensures the value is properly quoted and cast to the enum type.
+ *
+ * Examples:
+ * - "active" with type "status" -> "'active'::status"
+ * - "status::active" with type "status" -> "'active'::status"
+ * - "'active'::status" with type "status" -> "'active'::status" (already formatted)
+ * - "NULL" -> "NULL" (special value)
+ */
+function formatEnumDefault(value: string, enumType: string): string {
+  if (value === "NULL") {
+    return value;
+  }
+
+  // Check if already in PostgreSQL cast format: 'value'::type
+  const alreadyFormatted = /^'[^']*'::\w+$/.test(value);
+  if (alreadyFormatted) {
+    return value;
+  }
+
+  // If has type cast (type::value), convert it
+  if (value.includes("::")) {
+    return formatTypeCast(value);
+  }
+
+  // Plain identifier, wrap in quotes and add type cast
+  return `'${value}'::${enumType}`;
+}
+
 // ============================================================================
 // Generator Context
 // ============================================================================
@@ -164,13 +215,15 @@ function escapeRegExp(str: string): string {
 function expandCheckExpression(expr: string, ctx: GeneratorContext): string {
   let result = expr;
 
+  // Expand template variables
   for (const [param, value] of ctx.templateSubs) {
     const escapedParam = escapeRegExp(param);
     const pattern = new RegExp(`\\{${escapedParam}\\}`, "g");
     result = result.replace(pattern, value);
   }
 
-  result = result.replace(/(\w+)::(\w+)/g, "'$2'::$1");
+  // Format type casts (type::value -> 'value'::type)
+  result = formatTypeCast(result);
 
   return result;
 }
@@ -185,6 +238,9 @@ function generateEnumSql(enumDecl: EnumDecl, ctx: GeneratorContext): void {
   if (ctx.generatedEnums.has(name)) return;
   ctx.generatedEnums.add(name);
 
+  // Add to enums map so it can be referenced for default value formatting
+  ctx.enums.set(name, enumDecl);
+
   const values = enumDecl.values.map((v) => `'${v}'`).join(", ");
   ctx.enumSql.push(`DO $$ BEGIN
     CREATE TYPE ${name} AS ENUM (${values});
@@ -211,9 +267,17 @@ function generateColumnSql(col: ColumnDef, ctx: GeneratorContext): string {
       case "Unique":
         parts.push("UNIQUE");
         break;
-      case "Default":
-        parts.push(`DEFAULT ${constraint.value ?? "NULL"}`);
+      case "Default": {
+        let defaultValue = constraint.value ?? "NULL";
+
+        const enumTypeName = col.dataType.toLowerCase();
+        if (ctx.enums.has(enumTypeName)) {
+          defaultValue = formatEnumDefault(defaultValue, enumTypeName);
+        }
+
+        parts.push(`DEFAULT ${defaultValue}`);
         break;
+      }
       case "Reference": {
         let tableName = constraint.table ?? "";
         if (ctx.tableToSchema.has(tableName)) {
@@ -234,9 +298,14 @@ function generateColumnSql(col: ColumnDef, ctx: GeneratorContext): string {
   return [...parts, ...postConstraints].join(" ");
 }
 
+/**
+ * Generate CREATE INDEX SQL statement.
+ * Used for both schema-level indexes and per-instance indexes.
+ */
 function generateIndexSql(tableName: string, index: IndexDef, ctx: GeneratorContext): string {
-  const columns = index.columns.map((c) => expandTemplate(c, ctx)).join(", ");
-  const columnNames = index.columns.map((c) => expandTemplate(c, ctx)).join("_");
+  const expandedColumns = index.columns.map((c) => expandTemplate(c, ctx));
+  const columns = expandedColumns.join(", ");
+  const columnNames = expandedColumns.join("_");
   const indexName = `idx_${tableName}_${columnNames}`;
   const unique = index.unique === true ? "UNIQUE " : "";
   const using = index.using ? `USING ${index.using} ` : "";
@@ -252,7 +321,7 @@ function generateCheckSql(_tableName: string, check: CheckDef, ctx: GeneratorCon
 function generateTriggerSql(
   tableName: string,
   trigger: TriggerDef,
-  _ctx: GeneratorContext
+  _ctx: GeneratorContext,
 ): string {
   const timing = trigger.timing.toUpperCase();
   const event = trigger.event.toUpperCase();
@@ -293,7 +362,7 @@ function resolveMixins(schema: SchemaDecl, ctx: GeneratorContext): SchemaBodyIte
 function resolveSchema(
   schema: SchemaDecl,
   tableName: string,
-  ctx: GeneratorContext
+  ctx: GeneratorContext,
 ): ResolvedSchema {
   const allItems = resolveMixins(schema, ctx);
 
@@ -444,14 +513,14 @@ function processInstantiation(decl: Instantiation, ctx: GeneratorContext): void
 }
 
 function processPerInstanceIndex(decl: PerInstanceIndex, ctx: GeneratorContext): void {
-  const columns = decl.columns.join(", ");
-  const indexName = `idx_${decl.tableName}_${decl.columns.join("_")}`;
-  const unique = decl.unique === true ? "UNIQUE " : "";
-  const using = decl.using ? `USING ${decl.using} ` : "";
-
-  ctx.perInstanceIndexSql.push(
-    `CREATE ${unique}INDEX ${indexName} ON ${decl.tableName} ${using}(${columns});`
-  );
+  const indexDef: IndexDef = {
+    type: "IndexDef",
+    columns: decl.columns,
+    unique: decl.unique,
+    using: decl.using,
+  };
+
+  ctx.perInstanceIndexSql.push(generateIndexSql(decl.tableName, indexDef, ctx));
 }
 
 // ============================================================================

package/src/parser.ts

@@ -1028,23 +1028,106 @@ class CstToAstVisitor {
   }
 
   private reconstructCheckExpression(node: CstNode): string {
-    const parts: string[] = [];
+    // Collect all tokens/nodes with their positions
+    const tokens: {
+      image: string;
+      startOffset: number;
+      isParenExpr: boolean;
+    }[] = [];
 
     for (const key of Object.keys(node.children)) {
       const children = node.children[key];
       if (!children) continue;
 
       for (const child of children) {
-        if ("image" in child) {
-          parts.push(child.image);
+        if ("image" in child && "startOffset" in child) {
+          // It's a token
+          const startOffset = typeof child.startOffset === "number" ? child.startOffset : 0;
+          tokens.push({
+            image: child.image,
+            startOffset,
+            isParenExpr: false,
+          });
         } else if ("children" in child && key === "checkExpression") {
+          // It's a nested checkExpression - recursively reconstruct it
+          // Note: The LParen and RParen tokens from the grammar rule are collected
+          // separately as tokens in the parent, so we don't wrap the result here
           const inner = this.reconstructCheckExpression(child);
-          if (inner) parts.push(`(${inner})`);
+          if (inner) {
+            // Get the position from the first token in the child
+            let minOffset = Infinity;
+            for (const childKey of Object.keys(child.children)) {
+              const childChildren = child.children[childKey];
+              if (childChildren) {
+                for (const c of childChildren) {
+                  if ("startOffset" in c && typeof c.startOffset === "number") {
+                    minOffset = Math.min(minOffset, c.startOffset);
+                  }
+                }
+              }
+            }
+            tokens.push({
+              image: inner,
+              startOffset: minOffset === Infinity ? 0 : minOffset,
+              isParenExpr: false,
+            });
+          }
+        }
+      }
+    }
+
+    // Sort tokens by their position in the source
+    tokens.sort((a, b) => a.startOffset - b.startOffset);
+
+    // Join tokens intelligently - add spaces only where needed
+    let result = "";
+    for (let i = 0; i < tokens.length; i++) {
+      const current = tokens[i];
+      const prev = i > 0 ? tokens[i - 1] : null;
+
+      if (!current) continue;
+      const currentImage = current.image;
+
+      // Tokens that should not have a space before them
+      const noSpaceBefore = [")", ",", ".", "::", ">", "<"];
+      // Tokens that should not have a space after them
+      const noSpaceAfter = ["(", ".", "::"];
+
+      // Add space if needed
+      if (prev && !current.isParenExpr) {
+        const prevImage = prev.image;
+        const prevLastChar = prevImage[prevImage.length - 1] ?? "";
+
+        // Special case: if prev is > or < and current is =, don't add space (for >=, <=)
+        const isCompoundOperator = (prevImage === ">" || prevImage === "<") && currentImage === "=";
+        // Add space before comparison operators (unless making a compound one)
+        const isOperatorStart =
+          (currentImage === ">" || currentImage === "<") &&
+          !noSpaceAfter.includes(prevImage) &&
+          prevLastChar !== "(";
+
+        const needsSpace =
+          (!noSpaceBefore.includes(currentImage) &&
+            !noSpaceAfter.includes(prevImage) &&
+            prevLastChar !== "(" &&
+            !isCompoundOperator) ||
+          isOperatorStart;
+
+        if (needsSpace) {
+          result += " ";
+        }
+      } else if (prev && current.isParenExpr) {
+        // For parenthesized expressions, add space unless previous ends with (
+        const prevImage = prev.image;
+        const prevLastChar = prevImage[prevImage.length - 1] ?? "";
+        if (prevLastChar !== "(") {
+          result += " ";
         }
       }
+      result += currentImage;
     }
 
-    return parts.join(" ");
+    return result;
   }
 
   private visitIndexDef(node: CstNode): IndexDef {