zig-pug 0.4.0 → 4.0.1

package/README.md

@@ -14,7 +14,9 @@ High-performance Pug template engine powered by Zig and mujs.
 - ✅ **Conditionals** - if/else/unless
 - ✅ **Mixins** - Reusable components
 - ✅ **Dual package** - CommonJS (`require`) and ES Modules (`import`)
+- ✅ **TypeScript support** - Full type definitions included
 - ✅ **Bun.js compatible** - 2-5x faster than Node.js
+- ✅ **Structured errors** - Detailed error messages with line numbers, hints, and context
 - ⚡ **Native performance** - Written in Zig, compiled to native code
 - 🔋 **Zero dependencies** - Only Zig and embedded mujs
 - 🌍 **i18n ready** - Spanish, Portuguese, French, German, and more
@@ -122,6 +124,59 @@ bun run app.js
 
 See [examples/bun/](https://github.com/carlos-sweb/zig-pug/tree/main/examples/bun) for complete examples.
 
+## TypeScript Support
+
+zig-pug includes full TypeScript definitions for enhanced development experience with IntelliSense and type safety.
+
+### Basic Usage
+
+```typescript
+import { compile, PugCompiler, ZigPugCompilationError } from 'zig-pug';
+
+// Simple compilation with type inference
+const html: string = compile('p Hello #{name}', { name: 'TypeScript' });
+
+// Using PugCompiler class
+const compiler: PugCompiler = new PugCompiler();
+compiler
+    .setString('title', 'My Page')
+    .setNumber('count', 42)
+    .setBool('active', true);
+
+const result: string = compiler.compile('h1= title');
+```
+
+### Error Handling with Types
+
+```typescript
+try {
+    const html = compile(template, variables);
+} catch (error) {
+    const err = error as ZigPugCompilationError;
+
+    if (err.compilationErrors) {
+        const { errorCount, errors } = err.compilationErrors;
+
+        errors.forEach(e => {
+            console.error(`Line ${e.line}: ${e.message}`);
+            if (e.detail) console.error(`  Detail: ${e.detail}`);
+            if (e.hint) console.error(`  Hint: ${e.hint}`);
+        });
+    }
+}
+```
+
+### Available Types
+
+- `PugCompiler` - Main compiler class
+- `PugVariables` - Type for template variables
+- `CompilationErrorInfo` - Individual error information
+- `CompilationErrors` - Collection of compilation errors
+- `ZigPugCompilationError` - Extended Error with compilation details
+- `ErrorType` - Error type classification enum
+
+See [examples/nodejs/08-typescript-example.ts](https://github.com/carlos-sweb/zig-pug/tree/main/examples/nodejs/08-typescript-example.ts) for complete TypeScript examples.
+
 ## Pug Syntax
 
 ### Tags and Attributes

package/binding.c

@@ -21,6 +21,8 @@ extern int zigpug_set_array_json(ZigPugContext* ctx, const char* key, const char
 extern int zigpug_set_object_json(ZigPugContext* ctx, const char* key, const char* json_str);
 extern void zigpug_free_string(char* str);
 extern const char* zigpug_version(void);
+extern size_t zigpug_get_error_count(ZigPugContext* ctx);
+extern int zigpug_get_error(ZigPugContext* ctx, size_t index, size_t* line_out, const char** message_out, const char** detail_out, const char** hint_out);
 
 // Wrapper for ZigPugContext to store in JavaScript
 typedef struct {
@@ -295,7 +297,74 @@ static napi_value Compile(napi_env env, napi_callback_info info) {
     free(template);
 
     if (!html) {
-        napi_throw_error(env, NULL, "Failed to compile template");
+        // Get error information
+        size_t error_count = zigpug_get_error_count(wrapper->ctx);
+
+        if (error_count > 0) {
+            // Create structured error object
+            napi_value error_obj;
+            napi_create_object(env, &error_obj);
+
+            // Add error count
+            napi_value count_value;
+            napi_create_uint32(env, (uint32_t)error_count, &count_value);
+            napi_set_named_property(env, error_obj, "errorCount", count_value);
+
+            // Add errors array
+            napi_value errors_array;
+            napi_create_array_with_length(env, error_count, &errors_array);
+
+            for (size_t i = 0; i < error_count; i++) {
+                size_t line;
+                const char* message;
+                const char* detail;
+                const char* hint;
+
+                if (zigpug_get_error(wrapper->ctx, i, &line, &message, &detail, &hint)) {
+                    napi_value err_obj;
+                    napi_create_object(env, &err_obj);
+
+                    // Add line number
+                    napi_value line_value;
+                    napi_create_uint32(env, (uint32_t)line, &line_value);
+                    napi_set_named_property(env, err_obj, "line", line_value);
+
+                    // Add message
+                    napi_value message_value;
+                    napi_create_string_utf8(env, message, NAPI_AUTO_LENGTH, &message_value);
+                    napi_set_named_property(env, err_obj, "message", message_value);
+
+                    // Add detail if present
+                    if (detail) {
+                        napi_value detail_value;
+                        napi_create_string_utf8(env, detail, NAPI_AUTO_LENGTH, &detail_value);
+                        napi_set_named_property(env, err_obj, "detail", detail_value);
+                    }
+
+                    // Add hint if present
+                    if (hint) {
+                        napi_value hint_value;
+                        napi_create_string_utf8(env, hint, NAPI_AUTO_LENGTH, &hint_value);
+                        napi_set_named_property(env, err_obj, "hint", hint_value);
+                    }
+
+                    napi_set_element(env, errors_array, (uint32_t)i, err_obj);
+                }
+            }
+
+            napi_set_named_property(env, error_obj, "errors", errors_array);
+
+            // Throw the structured error
+            napi_throw_error(env, NULL, "Template compilation failed");
+            napi_value error_instance;
+            napi_get_and_clear_last_exception(env, &error_instance);
+
+            // Add our structured error data to the error object
+            napi_set_named_property(env, error_instance, "compilationErrors", error_obj);
+            napi_throw(env, error_instance);
+        } else {
+            napi_throw_error(env, NULL, "Failed to compile template");
+        }
         return NULL;
     }
 

package/binding.gyp

@@ -13,10 +13,29 @@
           "libraries": [
             "<(module_root_dir)/prebuilts/win32-<(target_arch)/zig-pug.lib"
           ]
-        }, {
+        }],
+        ["OS=='mac'", {
           "libraries": [
             "-lm",
-            "<(module_root_dir)/prebuilts/<(OS)-<(target_arch)/libzig-pug.a"
+            "../prebuilts/darwin-<(target_arch)/libzig-pug.a"
+          ],
+          "cflags": [
+            "-std=c99"
+          ]
+        }],
+        ["OS=='android'", {
+          "libraries": [
+            "-lm",
+            "../prebuilts/linux-<(target_arch)/libzig-pug.a"
+          ],
+          "cflags": [
+            "-std=c99"
+          ]
+        }],
+        ["OS=='linux'", {
+          "libraries": [
+            "-lm",
+            "../prebuilts/linux-<(target_arch)/libzig-pug.a"
           ],
           "cflags": [
             "-std=c99"

package/include/zigpug.h

@@ -106,6 +106,54 @@ bool zigpug_set_int(ZigPugContext* ctx, const char* key, int64_t value);
  */
 bool zigpug_set_bool(ZigPugContext* ctx, const char* key, bool value);
 
+/**
+ * Get the number of compilation errors from the last compile call
+ *
+ * @param ctx Context handle
+ * @return Number of errors, or 0 if no errors or no compilation done
+ *
+ * Example:
+ *   char* html = zigpug_compile(ctx, pug);
+ *   if (!html) {
+ *       size_t error_count = zigpug_get_error_count(ctx);
+ *       printf("Compilation failed with %zu error(s)\n", error_count);
+ *   }
+ */
+size_t zigpug_get_error_count(ZigPugContext* ctx);
+
+/**
+ * Get a specific compilation error by index
+ *
+ * @param ctx Context handle
+ * @param index Error index (0 to error_count-1)
+ * @param line_out Output parameter for line number (can be NULL)
+ * @param message_out Output parameter for error message (can be NULL, do not free)
+ * @param detail_out Output parameter for detail (can be NULL, do not free, may be null)
+ * @param hint_out Output parameter for hint (can be NULL, do not free, may be null)
+ * @return true if error exists at index, false otherwise
+ *
+ * Example:
+ *   for (size_t i = 0; i < error_count; i++) {
+ *       size_t line;
+ *       const char* message;
+ *       const char* detail;
+ *       const char* hint;
+ *       if (zigpug_get_error(ctx, i, &line, &message, &detail, &hint)) {
+ *           printf("Line %zu: %s\n", line, message);
+ *           if (detail) printf("  %s\n", detail);
+ *           if (hint) printf("  Hint: %s\n", hint);
+ *       }
+ *   }
+ */
+bool zigpug_get_error(
+    ZigPugContext* ctx,
+    size_t index,
+    size_t* line_out,
+    const char** message_out,
+    const char** detail_out,
+    const char** hint_out
+);
+
 /**
  * Free a string returned by zig-pug
  *

package/index.d.ts

@@ -0,0 +1,294 @@
+/**
+ * zig-pug TypeScript definitions
+ * Pug template engine powered by Zig
+ */
+
+/**
+ * Error type classification
+ */
+export type ErrorType =
+    | 'LoopIterableEvalFailed'
+    | 'ConditionalEvalFailed'
+    | 'InterpolationEvalFailed'
+    | 'AttributeEvalFailed'
+    | 'CodeExecutionFailed'
+    | 'CaseEvalFailed'
+    | 'MixinNotFound'
+    | 'IncludeFileNotFound'
+    | 'IncludeParseError'
+    | 'ExtendsFileNotFound'
+    | 'ExtendsParseError';
+
+/**
+ * Structured compilation error information
+ */
+export interface CompilationErrorInfo {
+    /** Error type classification */
+    type?: ErrorType;
+    /** Line number where the error occurred */
+    line: number;
+    /** Error message */
+    message: string;
+    /** Additional detail/context (e.g., expression, variable name) */
+    detail?: string;
+    /** Hint to help fix the error */
+    hint?: string;
+}
+
+/**
+ * Compilation errors container
+ */
+export interface CompilationErrors {
+    /** Total number of errors */
+    errorCount: number;
+    /** Array of individual error details */
+    errors: CompilationErrorInfo[];
+}
+
+/**
+ * Extended Error with compilation details
+ */
+export interface ZigPugCompilationError extends Error {
+    /** Structured compilation error information */
+    compilationErrors?: CompilationErrors;
+}
+
+/**
+ * Supported variable types
+ */
+export type PugVariable = string | number | boolean | any[] | Record<string, any>;
+
+/**
+ * Variables object for template compilation
+ */
+export interface PugVariables {
+    [key: string]: PugVariable;
+}
+
+/**
+ * PugCompiler class for advanced usage with reusable context
+ *
+ * @example
+ * ```typescript
+ * const compiler = new PugCompiler();
+ * compiler.set('title', 'My Page');
+ * compiler.setArray('items', ['a', 'b', 'c']);
+ * const html = compiler.compile('h1= title');
+ * ```
+ */
+export class PugCompiler {
+    /**
+     * Create a new PugCompiler instance
+     * @throws {Error} If context creation fails
+     */
+    constructor();
+
+    /**
+     * Set a variable (auto-detects type)
+     * @param key - Variable name
+     * @param value - Variable value (string, number, boolean, array, or object)
+     * @returns This compiler instance for chaining
+     * @throws {TypeError} If value type is not supported
+     *
+     * @example
+     * ```typescript
+     * compiler.set('name', 'John');
+     * compiler.set('age', 30);
+     * compiler.set('active', true);
+     * compiler.set('tags', ['a', 'b']);
+     * compiler.set('user', { id: 1, name: 'John' });
+     * ```
+     */
+    set(key: string, value: PugVariable): this;
+
+    /**
+     * Set a string variable
+     * @param key - Variable name
+     * @param value - String value
+     * @returns This compiler instance for chaining
+     * @throws {TypeError} If key or value is not a string
+     * @throws {Error} If setting the variable fails
+     *
+     * @example
+     * ```typescript
+     * compiler.setString('title', 'Hello World');
+     * ```
+     */
+    setString(key: string, value: string): this;
+
+    /**
+     * Set a number variable
+     * @param key - Variable name
+     * @param value - Number value
+     * @returns This compiler instance for chaining
+     * @throws {TypeError} If key is not a string or value is not a number
+     * @throws {Error} If setting the variable fails
+     *
+     * @example
+     * ```typescript
+     * compiler.setNumber('count', 42);
+     * compiler.setNumber('price', 19.99);
+     * ```
+     */
+    setNumber(key: string, value: number): this;
+
+    /**
+     * Set a boolean variable
+     * @param key - Variable name
+     * @param value - Boolean value
+     * @returns This compiler instance for chaining
+     * @throws {TypeError} If key is not a string or value is not a boolean
+     * @throws {Error} If setting the variable fails
+     *
+     * @example
+     * ```typescript
+     * compiler.setBool('isActive', true);
+     * compiler.setBool('hasPermission', false);
+     * ```
+     */
+    setBool(key: string, value: boolean): this;
+
+    /**
+     * Set an array variable
+     * @param key - Variable name
+     * @param value - Array value
+     * @returns This compiler instance for chaining
+     * @throws {TypeError} If key is not a string or value is not an array
+     * @throws {Error} If setting the variable fails
+     *
+     * @example
+     * ```typescript
+     * compiler.setArray('items', ['Apple', 'Banana', 'Cherry']);
+     * compiler.setArray('numbers', [1, 2, 3, 4, 5]);
+     * ```
+     */
+    setArray(key: string, value: any[]): this;
+
+    /**
+     * Set an object variable
+     * @param key - Variable name
+     * @param value - Plain object (not array)
+     * @returns This compiler instance for chaining
+     * @throws {TypeError} If key is not a string or value is not a plain object
+     * @throws {Error} If setting the variable fails
+     *
+     * @example
+     * ```typescript
+     * compiler.setObject('user', {
+     *     name: 'John',
+     *     age: 30,
+     *     email: 'john@example.com'
+     * });
+     * ```
+     */
+    setObject(key: string, value: Record<string, any>): this;
+
+    /**
+     * Set multiple variables from an object
+     * @param variables - Object with key-value pairs
+     * @returns This compiler instance for chaining
+     *
+     * @example
+     * ```typescript
+     * compiler.setVariables({
+     *     title: 'My Page',
+     *     count: 10,
+     *     active: true,
+     *     items: ['a', 'b']
+     * });
+     * ```
+     */
+    setVariables(variables: PugVariables): this;
+
+    /**
+     * Compile a Pug template to HTML
+     * @param template - Pug template string
+     * @returns Compiled HTML string
+     * @throws {TypeError} If template is not a string
+     * @throws {ZigPugCompilationError} If compilation fails with structured error info
+     * @throws {Error} If compilation fails for other reasons
+     *
+     * @example
+     * ```typescript
+     * try {
+     *     const html = compiler.compile('h1= title');
+     *     console.log(html);
+     * } catch (error) {
+     *     if ((error as ZigPugCompilationError).compilationErrors) {
+     *         const { errors } = (error as ZigPugCompilationError).compilationErrors!;
+     *         errors.forEach(err => {
+     *             console.error(`Line ${err.line}: ${err.message}`);
+     *         });
+     *     }
+     * }
+     * ```
+     */
+    compile(template: string): string;
+
+    /**
+     * Compile a template with variables in one call
+     * @param template - Pug template string
+     * @param variables - Variables to set before compiling
+     * @returns Compiled HTML string
+     * @throws {TypeError} If template is not a string
+     * @throws {ZigPugCompilationError} If compilation fails
+     *
+     * @example
+     * ```typescript
+     * const html = compiler.render('h1= title', { title: 'Hello' });
+     * ```
+     */
+    render(template: string, variables?: PugVariables): string;
+}
+
+/**
+ * Compile a Pug template string to HTML (simple API)
+ * @param template - Pug template string
+ * @param variables - Optional variables for interpolation
+ * @returns Compiled HTML string
+ * @throws {ZigPugCompilationError} If compilation fails
+ *
+ * @example
+ * ```typescript
+ * const html = compile('p Hello #{name}!', { name: 'World' });
+ * console.log(html); // <p>Hello World!</p>
+ * ```
+ */
+export function compile(template: string, variables?: PugVariables): string;
+
+/**
+ * Compile a Pug template from a file
+ * @param filename - Path to .pug file
+ * @param variables - Optional variables for interpolation
+ * @returns Compiled HTML string
+ * @throws {Error} If file cannot be read
+ * @throws {ZigPugCompilationError} If compilation fails
+ *
+ * @example
+ * ```typescript
+ * const html = compileFile('./views/index.pug', {
+ *     title: 'Home',
+ *     user: { name: 'John' }
+ * });
+ * ```
+ */
+export function compileFile(filename: string, variables?: PugVariables): string;
+
+/**
+ * Get zig-pug version string
+ * @returns Version string (e.g., "0.4.0")
+ *
+ * @example
+ * ```typescript
+ * console.log(`Using zig-pug v${version()}`);
+ * ```
+ */
+export function version(): string;
+
+// Default export
+export default {
+    PugCompiler,
+    compile,
+    compileFile,
+    version
+};

package/index.mjs

@@ -121,14 +121,60 @@ export class PugCompiler {
         return this;
     }
 
+    /**
+     * Set an array variable in the template context
+     * @param {string} key - Variable name
+     * @param {Array} value - Array value
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    setArray(key, value) {
+        if (typeof key !== 'string') {
+            throw new TypeError('Key must be a string');
+        }
+        if (!Array.isArray(value)) {
+            throw new TypeError('Value must be an array');
+        }
+
+        const success = binding.setArray(this.context, key, value);
+        if (!success) {
+            throw new Error(`Failed to set array variable: ${key}`);
+        }
+        return this;
+    }
+
+    /**
+     * Set an object variable in the template context
+     * @param {string} key - Variable name
+     * @param {Object} value - Object value (plain object, not array)
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    setObject(key, value) {
+        if (typeof key !== 'string') {
+            throw new TypeError('Key must be a string');
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new TypeError('Value must be a plain object');
+        }
+
+        const success = binding.setObject(this.context, key, value);
+        if (!success) {
+            throw new Error(`Failed to set object variable: ${key}`);
+        }
+        return this;
+    }
+
     /**
      * Set a variable (automatically detects type)
      * @param {string} key - Variable name
-     * @param {string|number|boolean} value - Value of any supported type
+     * @param {string|number|boolean|Array|Object} value - Value of any supported type
      * @returns {PugCompiler} - Returns this for chaining
      */
     set(key, value) {
-        if (typeof value === 'string') {
+        if (Array.isArray(value)) {
+            return this.setArray(key, value);
+        } else if (typeof value === 'object' && value !== null) {
+            return this.setObject(key, value);
+        } else if (typeof value === 'string') {
             return this.setString(key, value);
         } else if (typeof value === 'number') {
             return this.setNumber(key, value);

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "zig-pug",
-  "version": "0.4.0",
-  "description": "High-performance Pug template engine powered by Zig and mujs. Native N-API addon with ES5.1 JavaScript support, full UTF-8 (emoji, accents), documentation comments (//!), and fast compilation. Compatible with Node.js and Bun.",
+  "version": "4.0.1",
+  "description": "High-performance Pug template engine powered by Zig and mujs. Native N-API addon with ES5.1 JavaScript support, full UTF-8 (emoji, accents), Builder API for dynamic data construction, comprehensive C/C++ API, and fast compilation. Compatible with Node.js and Bun.",
   "type": "commonjs",
   "main": "index.js",
+  "types": "index.d.ts",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "import": "./index.mjs",
       "require": "./index.js"
     }
@@ -14,7 +16,8 @@
     "install": "node install.js",
     "postinstall": "node install.js",
     "build": "node-gyp configure build",
-    "rebuild": "node-gyp rebuild",
+    "rebuild": "npm run prebuild-fix && node-gyp rebuild",
+    "prebuild-fix": "node prebuild-fix.js",
     "clean": "node-gyp clean",
     "test": "node test/test.js",
     "build-prebuilts": "./build-prebuilts.sh",
@@ -55,7 +58,14 @@
     "spanish",
     "portuguese",
     "french",
-    "german"
+    "german",
+    "c-api",
+    "c++",
+    "cpp",
+    "ffi",
+    "builder-api",
+    "dynamic-data",
+    "type-safe"
   ],
   "author": {
     "name": "zig-pug contributors",
@@ -87,7 +97,9 @@
   "files": [
     "index.js",
     "index.mjs",
+    "index.d.ts",
     "install.js",
+    "prebuild-fix.js",
     "binding.c",
     "binding.gyp",
     "common.gypi",

package/prebuild-fix.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Fix for node-gyp build issues in Termux/Android
+// Creates necessary directories and files that make expects to exist
+
+const fs = require('fs');
+const path = require('path');
+
+const depsDir = path.join(__dirname, 'build', 'Release', '.deps', 'Release', 'obj.target', 'zigpug');
+const depsFile = path.join(depsDir, 'binding.o.d.raw');
+
+try {
+  // Create directory structure
+  fs.mkdirSync(depsDir, { recursive: true });
+  
+  // Create empty file if it doesn't exist
+  if (!fs.existsSync(depsFile)) {
+    fs.writeFileSync(depsFile, '');
+  }
+  
+  console.log('✓ Pre-build fix applied for Termux/Android compatibility');
+} catch (err) {
+  // Ignore errors - this is just a workaround
+  console.log('⚠ Pre-build fix skipped:', err.message);
+}