add auto update checker

Author: muhammad-fiaz

README.md

@@ -111,6 +111,8 @@ pub fn main() !void {
 }
 ```
 
+> **Note:** zigantic automatically checks for updates when using JSON functions. To disable, call `z.disableUpdateCheck()` at the start of your program.
+
 ### JSON Parsing with Validation
 
 ```zig

docs/.vitepress/config.mts

@@ -49,6 +49,7 @@ export default defineConfig({
             { text: 'Validation Types', link: '/guide/validation-types' },
             { text: 'JSON Parsing', link: '/guide/json-parsing' },
             { text: 'Error Handling', link: '/guide/error-handling' },
+            { text: 'Version & Updates', link: '/guide/version-updates' },
           ],
         },
       ],

docs/api/errors.md

@@ -119,3 +119,59 @@ if (!result.isValid()) {
     defer allocator.free(json_errors);
 }
 ```
+
+## Version Utilities
+
+```zig
+z.getVersion()       // "0.0.1"
+z.getVersionString() // "v0.0.1"
+z.ISSUES_URL         // GitHub issues URL
+```
+
+## Internal Error Reporting
+
+::: warning
+Use only for **library bugs**, NOT for validation errors!
+:::
+
+```zig
+// Report unexpected internal error
+z.reportInternalError("Unexpected null in parser");
+
+// Report with error code
+z.reportInternalErrorWithCode(error.OutOfMemory);
+```
+
+Output:
+
+```
+[ZIGANTIC ERROR] Unexpected null in parser
+
+If you believe this is a bug in zigantic, please report it at:
+  https://github.com/muhammad-fiaz/zigantic/issues
+```
+
+## Update Checking
+
+```zig
+// Disable automatic update checking (call before using library)
+z.disableUpdateCheck();
+
+// Or use custom config
+z.setConfig(.{
+    .auto_update_check = false,
+    .show_update_notifications = false,
+});
+
+// Manual update check (background)
+if (z.checkForUpdates(allocator)) |thread| {
+    defer thread.join();
+}
+
+// Manual update check (synchronous)
+var info = try z.checkForUpdatesSync(allocator);
+defer info.deinit();
+if (info.update_available) {
+    std.debug.print("Update: {s}\n", .{info.latest_version});
+}
+```

docs/api/json.md

@@ -2,6 +2,10 @@
 
 JSON parsing and serialization.
 
+::: tip Automatic Updates
+JSON functions (`fromJson`, `toJson`, `toJsonPretty`) automatically trigger a background update check on first use. To disable, call `z.disableUpdateCheck()` before using these functions.
+:::
+
 ## Parsing
 
 ### z.fromJson

docs/guide/error-handling.md

@@ -115,3 +115,34 @@ var errors2 = z.errors.ErrorList.init(allocator);
 // ... add errors ...
 try errors1.merge(errors2);
 ```
+
+## Validation Errors vs Library Bugs
+
+::: tip Important Distinction
+**Validation errors** are expected behavior when users provide invalid data. Handle them normally.
+
+**Library bugs** are unexpected internal errors that might indicate a problem with zigantic itself.
+:::
+
+### Validation Errors (Expected)
+
+```zig
+// This is normal - user provided invalid data
+if (z.String(3, 50).init("Jo")) |name| {
+    std.debug.print("Valid: {s}\n", .{name.get()});
+} else |err| {
+    // Handle normally - this is NOT a library bug
+    std.debug.print("Error: {s}\n", .{z.errorMessage(err)});
+}
+```
+
+### Library Bugs (Unexpected)
+
+Only use `reportInternalError` for unexpected situations that might be library bugs:
+
+```zig
+// Only for unexpected internal errors
+z.reportInternalError("Unexpected null during parsing");
+```
+
+This will print a message with the GitHub issues URL for reporting.

docs/guide/getting-started.md

@@ -56,14 +56,18 @@ pub fn build(b: *std.Build) void {
 ### Step 3: Import and use
 
 ```zig
+const std = @import("std");
 const z = @import("zigantic");
 
 pub fn main() !void {
+    // Just use the library - no initialization needed!
     const name = try z.String(1, 50).init("Alice");
     std.debug.print("Hello, {s}!\n", .{name.get()});
 }
 ```
 
+> **Note:** zigantic automatically checks for updates when you use JSON functions. To disable this, call `z.disableUpdateCheck()` before using the library. See [Version & Updates](/guide/version-updates) for details.
+
 ## Your First Validation
 
 Let's validate some data:
@@ -185,4 +189,5 @@ zig build example    # Run basic example
 - **[Validation Types](/guide/validation-types)** - Complete type reference
 - **[JSON Parsing](/guide/json-parsing)** - Parse and serialize JSON
 - **[Error Handling](/guide/error-handling)** - Handle errors with codes
+- **[Version & Updates](/guide/version-updates)** - Automatic updates and error reporting
 - **[API Reference](/api/types)** - Full API documentation

docs/guide/version-updates.md

@@ -0,0 +1,211 @@
+# Version & Updates
+
+zigantic includes automatic version checking and error reporting features to help you stay up-to-date and report issues easily.
+
+## Automatic Update Checking
+
+zigantic **automatically** checks for updates in the background when you first use JSON functions (`fromJson`, `toJson`, `toJsonPretty`). No initialization is needed!
+
+When a new version is available, you'll see a log message:
+
+```
+info: [UPDATE] A newer release of zigantic is available: v0.1.0 (current 0.0.1)
+```
+
+### Basic Usage (Updates Enabled by Default)
+
+```zig
+const std = @import("std");
+const z = @import("zigantic");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+
+    // Just use the library - update check happens automatically!
+    const name = try z.String(1, 50).init("Alice");
+    std.debug.print("Hello, {s}!\n", .{name.get()});
+
+    // Update check triggers on first JSON use
+    const User = struct { name: z.String(1, 50) };
+    var result = try z.fromJson(User, "{\"name\": \"Bob\"}", gpa.allocator());
+    defer result.deinit();
+}
+```
+
+## Disabling Automatic Updates
+
+To disable automatic update checking, call `disableUpdateCheck()` **before** using any library functions:
+
+```zig
+const std = @import("std");
+const z = @import("zigantic");
+
+pub fn main() !void {
+    // Disable update checking (must be called before any other z.* functions)
+    z.disableUpdateCheck();
+
+    // Now use the library normally - no update checks will occur
+    const name = try z.String(1, 50).init("Alice");
+    std.debug.print("Hello, {s}!\n", .{name.get()});
+}
+```
+
+### Custom Configuration
+
+For more control, use `setConfig()`:
+
+```zig
+const z = @import("zigantic");
+
+pub fn main() !void {
+    // Customize configuration
+    z.setConfig(.{
+        .auto_update_check = false,      // Disable update checking
+        .show_update_notifications = false, // Disable notifications
+    });
+
+    // Use library...
+}
+```
+
+### Configuration Options
+
+| Option                      | Type   | Default | Description                           |
+| --------------------------- | ------ | ------- | ------------------------------------- |
+| `auto_update_check`         | `bool` | `true`  | Enable/disable automatic update check |
+| `show_update_notifications` | `bool` | `true`  | Show update notifications in log      |
+
+## Library Version
+
+Get the current version of zigantic:
+
+```zig
+const z = @import("zigantic");
+
+const ver = z.getVersion();       // "0.0.1"
+const full = z.getVersionString(); // "v0.0.1"
+```
+
+## Manual Update Checking
+
+You can also check for updates manually:
+
+### Background Check (Non-blocking)
+
+```zig
+const z = @import("zigantic");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+
+    // Start background update check
+    if (z.checkForUpdates(gpa.allocator())) |thread| {
+        // Optional: wait for check to complete on shutdown
+        defer thread.join();
+    }
+}
+```
+
+### Synchronous Check
+
+```zig
+const z = @import("zigantic");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+
+    // Check for updates synchronously
+    var info = try z.checkForUpdatesSync(gpa.allocator());
+    defer info.deinit();
+
+    if (info.update_available) {
+        std.debug.print("Update available: {s} (current: {s})\n", .{
+            info.latest_version,
+            info.current_version,
+        });
+    }
+}
+```
+
+## Internal Error Reporting
+
+::: warning
+The error reporting functions are for **library bugs only** - unexpected internal errors that might indicate a bug in zigantic itself.
+
+**Do NOT use these for validation errors!** Validation errors (like "value is too short") are expected behavior when users provide invalid data.
+:::
+
+### When to Use Error Reporting
+
+Use `reportInternalError` only when you encounter an unexpected situation in your own code that might be caused by a bug in zigantic:
+
+```zig
+const z = @import("zigantic");
+
+fn myLibraryFunction() !void {
+    // Some unexpected internal error occurred
+    // This might be a bug in zigantic's internals
+    z.reportInternalError("Unexpected null value in parsed result");
+    return error.InternalError;
+}
+```
+
+This prints:
+
+```
+[ZIGANTIC ERROR] Unexpected null value in parsed result
+
+If you believe this is a bug in zigantic, please report it at:
+  https://github.com/muhammad-fiaz/zigantic/issues
+```
+
+### Validation Errors (Do NOT Report)
+
+Validation errors are **expected behavior** - don't report them as bugs:
+
+```zig
+const z = @import("zigantic");
+
+pub fn main() void {
+    // This is normal - validation errors are expected!
+    if (z.String(3, 50).init("Jo")) |name| {
+        std.debug.print("Valid: {s}\n", .{name.get()});
+    } else |err| {
+        // Handle normally - DO NOT call reportError()
+        std.debug.print("Validation failed: {s}\n", .{z.errorMessage(err)});
+    }
+}
+```
+
+### Get Issues URL
+
+```zig
+const z = @import("zigantic");
+
+const url = z.ISSUES_URL;  // "https://github.com/muhammad-fiaz/zigantic/issues"
+```
+
+## API Reference
+
+### Functions
+
+| Function                           | Description                                             |
+| ---------------------------------- | ------------------------------------------------------- |
+| `disableUpdateCheck()`             | Disable automatic update checking                       |
+| `setConfig(config)`                | Set custom configuration                                |
+| `getConfig()`                      | Get current configuration                               |
+| `getVersion()`                     | Get version string (e.g., "0.0.1")                      |
+| `getVersionString()`               | Get full version (e.g., "v0.0.1")                       |
+| `checkForUpdates(allocator)`       | Manually check for updates in background                |
+| `checkForUpdatesSync(allocator)`   | Manually check for updates synchronously                |
+| `reportInternalError(msg)`         | Report internal library bug (not for validation errors) |
+| `reportInternalErrorWithCode(err)` | Report internal library bug with error code             |
+
+### Constants
+
+| Constant     | Description                          |
+| ------------ | ------------------------------------ |
+| `ISSUES_URL` | GitHub issues URL for reporting bugs |

docs/index.md

@@ -33,9 +33,9 @@ features:
   - icon: 🔄
     title: JSON Parsing
     details: Parse and serialize JSON with automatic validation, nested struct support, and default values.
-  - icon: ✅
-    title: 102 Tests
-    details: Comprehensive test coverage ensuring reliability and correctness across all features.
+  - icon: 🔔
+    title: Automatic Updates
+    details: Checks for library updates automatically in the background. Easily disable with one function call.
 ---
 
 <style>