ci: add standalone workflow with Codecov integration

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI Database
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: stable
+
+      - name: Run tests with coverage
+        run: |
+          go test ./... -covermode=atomic -coverprofile=coverage.out
+
+      - name: Show coverage %
+        run: |
+          echo "Total coverage:"
+          go tool cover -func=coverage.out | grep total
+
+      - name: Enforce minimum 80% coverage
+        run: |
+          pct=$(go tool cover -func=coverage.out | grep total | awk '{print substr($3, 1, length($3)-1)}')
+          echo "Coverage: $pct%"
+          awk -v p="$pct" 'BEGIN {exit !(p >= 80)}'
+
+      - name: Upload coverage report
+        if: success()
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.out
+          flags: common
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: true

.gitignore

@@ -0,0 +1,60 @@
+# IDEs
+.vscode/
+.idea/
+*.iml
+*.sublime-project
+*.sublime-workspace
+
+# Editor artifacts
+*~
+*.swp
+*.swo
+*.bak
+*.tmp
+
+# Dependency directories (if vendored)
+vendor/
+
+# Git metadata
+*.orig
+
+# OS-specific
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Binaries for programs and plugins
+bin/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+coverage.*
+*.coverprofile
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Logs
+logs/
+*.log
+*.out
+
+# local
+/docs/CHANGELOG.md
+/docs/releases/
+docs/_site/
+docs/public/
+public/
+
+# env file
+.env

CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/)  
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [v1.0.0] - 2025-09-19
+
+### Added
+
+- **Builders**
+    - `SelectBuilder` with structured condition handling and consistent `Build() (string, []any, error)` signature.
+    - Planned: `InsertBuilder`, `UpdateBuilder`, `DeleteBuilder`, and `UpsertBuilder` (to include full clause ordering
+      and validation rules in future versions).
+    - Support for conditions:
+        - `Where`, `WhereAnd`, and `WhereOr` with validation and normalization.
+    - Support for grouping and having clauses:
+        - `GroupBy`, `ThenGroupBy`.
+        - `Having`, `AndHaving`, `OrHaving`.
+    - Support for ordering and pagination:
+        - `OrderBy`, `ThenOrderBy`.
+        - Pagination with `Take` and `Skip`.
+- **Tokens**
+    - `Condition`: semantic-aware constructor with validation and dialect-aware rendering.
+    - `Field`: deterministic constructors (`New`, `NewWithTable`), aliased support, encapsulated token type.
+    - `Table`: constructors and helpers to define tables, aliases, and raw inputs with validation.
+    - `Join`: support for INNER, LEFT, RIGHT, CROSS, and NATURAL joins.
+- **Contracts**
+    - `BaseToken`: core identity and validation for all tokens.
+    - `Errorable`: tokens can mark themselves errored after construction.
+    - `Kindable`, `Identifiable`, `Aliasable`: unify token identity handling.
+    - `Rawable`, `Renderable`, `Stringable`, `Validable`: standardized behaviors for token rendering, debugging, and
+      validation.
+    - `Token`: aggregate contract for ownership and auditability.
+        - Currently implemented by **Field**, **Table**, **Join**, and **Condition** tokens.
+        - Future adoption planned for **Having**, **GroupBy**, and **OrderBy** tokens.
+- **Dialect Support**
+    - Introduced **generic dialect** (implemented) with `?` placeholder strategy.
+    - Other dialects are **planned** for future releases, including Postgres, MySQL, MariaDB, SQLite, MSSQL, Oracle,
+      DB2, Firebird, Informix, CockroachDB, TiDB, HANA, Snowflake, Redshift, Teradata, and ClickHouse.
+
+### Changed
+
+- Renamed `Column` → `Field`.
+- `SelectBuilder` constructor renamed from `NewSelect` → `New`.
+- Refactored `Field` into dedicated subpackage `db/token/field`.
+- Normalized resolver helpers (`ResolveExpression`, `ResolveCondition`, `IsValidSlice`).
+
+### Documentation
+
+- Comprehensive `doc.go` and `README.md` across builders, tokens, and contracts.
+- Dialect guide and developer best practices.
+- Runnable examples in `example_test.go` for every major component.
+
+### Tests & Coverage
+
+- 100% unit test coverage across builders, tokens, dialects, and helpers.
+- Extensive diagnostics for invalid fields, nil receivers, and missing sources.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Isidro Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -8,16 +8,16 @@ Entiqon/db is a modular SQL query engine for Go, designed for composable, type-s
 
 ## 🛠 Capabilities
 
-| Module                 | Feature                | Purpose                                                                    | Status      |
-|------------------------|------------------------|----------------------------------------------------------------------------|-------------|
-| [builder](./builder)   | [insert](./builder)    | High-level SQL builder for INSERT statements                               | 📝 Planned  |
-|                        | [select](./builder)    | High-level SQL builder for SELECT statements (stable and production-ready) | ✅ Stable    |
-|                        | [update](./builder)    | High-level SQL builder for UPDATE statements                               | 📝 Planned  |
-|                        | [delete](./builder)    | High-level SQL builder for DELETE statements                               | 📝 Planned  |
-|                        | [upsert](./builder)    | High-level SQL builder for UPSERT / MERGE statements                       | 📝 Planned  |
-| [token](./token)       | [field](./token/field) | Dialect-agnostic representation of SQL fields/expressions                  | ✅ Stable    |
+| Module                 | Feature                | Purpose                                                                    | Status     |
+|------------------------|------------------------|----------------------------------------------------------------------------|------------|
+| [builder](./builder)   | [insert](./builder)    | High-level SQL builder for INSERT statements                               | 📝 Planned |
+|                        | [select](./builder)    | High-level SQL builder for SELECT statements (stable and production-ready) | ✅ Stable   |
+|                        | [update](./builder)    | High-level SQL builder for UPDATE statements                               | 📝 Planned |
+|                        | [delete](./builder)    | High-level SQL builder for DELETE statements                               | 📝 Planned |
+|                        | [upsert](./builder)    | High-level SQL builder for UPSERT / MERGE statements                       | 📝 Planned |
+| [token](./token)       | [field](./token/field) | Dialect-agnostic representation of SQL fields/expressions                  | ✅ Stable   |
 |                        | [table](./token/table) | Dialect-agnostic representation of SQL tables/sources                      | ✅ Stable   |
-|                        | [join](./token/join)   | Dialect-agnostic representation of SQL join clauses                        | 🚧 Ongoing  |
+|                        | [join](./token/join)   | Dialect-agnostic representation of SQL join clauses                        | 🚧 Ongoing |
 | [contract](./contract) | BaseToken              | Common base for tokens (shared identity, ownership, validity checks)       | ✅ Stable   |
 |                        | Clonable               | Ensures semantic cloning of tokens without mutation                        | ✅ Stable   |
 |                        | Debuggable             | Provides developer-facing diagnostics (`Debug()`)                          | ✅ Stable   |

go.mod

@@ -1,3 +1,5 @@
 module github.com/entiqon/db
 
 go 1.24.2
+
+require github.com/entiqon/common v1.0.0

go.sum

@@ -0,0 +1,2 @@
+github.com/entiqon/common v1.0.0 h1:qoEJbcD1cjqxvlsMC6ow6CQUDMDO7wL3+a9H7CAFCQs=
+github.com/entiqon/common v1.0.0/go.mod h1:5AbyVPtxT/1impg3ljBvHd3y9/LTI63andE3CcMtHpk=

releases/release-notes-v1.0.0.md

@@ -0,0 +1,66 @@
+# Release Notes — db v1.0.0 (2025-09-19)
+
+This is the **first stable release** of the `entiqon/db` package.  
+It provides a robust SQL builder and token framework with strict validation, test coverage, and extensibility.
+
+---
+
+## ✨ Added
+
+### Builders
+- **SelectBuilder**:
+  - Structured condition handling with consistent `Build() (string, []any, error)` signature.
+  - Supports:
+    - Conditions: `Where`, `WhereAnd`, `WhereOr`.
+    - Grouping: `GroupBy`, `ThenGroupBy`.
+    - Having: `Having`, `AndHaving`, `OrHaving`.
+    - Ordering: `OrderBy`, `ThenOrderBy`.
+    - Pagination: `Take`, `Skip`.
+- **Planned**: `InsertBuilder`, `UpdateBuilder`, `DeleteBuilder`, and `UpsertBuilder` (to be included in future versions).
+
+### Tokens
+- **Condition**: semantic-aware constructor with validation and dialect-aware rendering.
+- **Field**: deterministic constructors (`New`, `NewWithTable`), aliased support, encapsulated token type.
+- **Table**: constructors and helpers to define tables, aliases, and raw inputs with validation.
+- **Join**: support for INNER, LEFT, RIGHT, CROSS, and NATURAL joins.
+
+### Contracts
+- **BaseToken**: core identity and validation for all tokens.
+- **Errorable**: tokens can mark themselves errored after construction.
+- **Kindable**, **Identifiable**, **Aliasable**: unify token identity handling.
+- **Token**: aggregate contract for ownership and auditability.
+  - Currently implemented by Field, Table, Join, and Condition tokens.
+  - Future adoption planned for Having, GroupBy, and OrderBy tokens.
+- **Rawable**, **Renderable**, **Stringable**, **Validable**: standardized behaviors for token rendering, debugging, and validation.
+
+### Dialect Support
+- Introduced **generic dialect** (implemented) using `?` placeholder strategy.
+- Other dialects are planned for future releases, including Postgres, MySQL, MariaDB, SQLite, MSSQL, Oracle, DB2, Firebird, Informix, CockroachDB, TiDB, HANA, Snowflake, Redshift, Teradata, and ClickHouse.
+
+---
+
+## 🔄 Changed
+- Renamed `Column` → `Field`.
+- `SelectBuilder` constructor renamed from `NewSelect` → `New`.
+- Refactored Field into dedicated subpackage `db/token/field`.
+- Normalized resolver helpers (`ResolveExpression`, `ResolveCondition`, `IsValidSlice`).
+
+---
+
+## 📚 Documentation
+- Comprehensive `doc.go` and `README.md` across builders, tokens, and contracts.
+- Dialect guide and developer best practices.
+- Runnable examples in `example_test.go` for every major component.
+
+---
+
+## 🧪 Tests & Coverage
+- 100% unit test coverage across builders, tokens, dialects, and helpers.
+- Extensive diagnostics for invalid fields, nil receivers, and missing sources.
+
+---
+
+## 📦 Availability
+```bash
+go get github.com/entiqon/[email protected]
+```