Merge pull request #1 from lupodevelop/import/sparkling-lib

Import/sparkling lib

workflows MUST be added in a separate PR

Author: lupodevelop

CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- (Unreleased changes go here)
+
+## [0.1.0] - 2025-11-09
+
+### Added
+
+- Initial release of sparkling — Gleam ClickHouse client
+- Type-safe query builder with composable DSL
+- Schema reflection and metadata discovery
+- Multiple format support (JSONEachRow, TabSeparated, CSV)
+- Changeset validation (Ecto-style)
+- HTTP resilience with exponential backoff retry
+- Hook system for extensibility and observability
+- Comprehensive test suite (unit + integration)
+- Docker setup for testing with ClickHouse
+- Query Module: composable SELECT/INSERT queries with type safety
+- Schema Module: table/column reflection via DESCRIBE queries
+- Repo Module: HTTP execution with authentication and error handling
+- Encode/Decode: format registry with pluggable handlers
+- Changeset: data validation and casting pipeline
+- Retry: automatic failure recovery with configurable backoff
+
+### Supported ClickHouse types
+
+- Primitives: UInt/Int 8/16/32/64, Float32/64, String, Bool
+- Date/Time: Date, Date32, DateTime, DateTime64
+- Complex: Array(T), Tuple(...), Map(K,V), Nested
+- Special: UUID, Enum8/16, Nullable(T), Decimal
+
+### Architecture
+
+- HTTP-only communication (no native protocol)
+- Zero external dependencies
+- Immutable, functional design
+- Hook-based extensibility
+- Comprehensive error handling
+
+### Testing
+
+- Unit tests with HTTP mocking
+- Integration tests with ClickHouse Docker
+- Round-trip tests for type safety
+- CI/CD with GitHub Actions
+
+### Documentation
+
+- API reference and examples
+- Quick start guide
+- Style guide for contributions
+
+<!-- Link references for versions -->
+[Unreleased]: https://github.com/lupodevelop/sparkling/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/lupodevelop/sparkling/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to Sparkling
+
+Thanks for your interest in contributing! A quick guide to help you get started.
+
+1. Fork the repository and create a feature branch from `main`.
+2. Follow the existing code style (run `gleam format --check` locally).
+3. Add unit tests when you add new behavior (`gleam test`).
+4. Open a Pull Request describing the change and link any relevant issues.
+
+PR checklist
+- [ ] Code follows style (`gleam format --check`)
+- [ ] Tests added/updated and passing (`gleam test`)
+- [ ] Documentation updated if needed (README, docs/)
+
+Maintainers will review PRs and request changes when necessary.

docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  clickhouse:
+    # Image can be overridden via environment variable CLICKHOUSE_IMAGE.
+    # Use format: clickhouse/clickhouse-server:<version>
+    image: "${CLICKHOUSE_IMAGE:-clickhouse/clickhouse-server:latest}"
+    container_name: sparkling_clickhouse_test
+    ports:
+      - "8123:8123"   # HTTP interface
+      - "9000:9000"   # Native protocol (for future)
+    environment:
+      CLICKHOUSE_DB: test_db
+      CLICKHOUSE_USER: test_user
+      CLICKHOUSE_PASSWORD: test_password
+      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
+    volumes:
+      - clickhouse_data:/var/lib/clickhouse
+    healthcheck:
+      test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+
+volumes:
+  clickhouse_data:

docs/examples/decode_examples.md

@@ -0,0 +1,11 @@
+# Examples extracted from sparkling/src/sparkling/decode.gleam
+
+## decode_json_each_row_streaming (usage example)
+
+```gleam
+let count = decode_json_each_row_streaming(
+  large_response,
+  my_decoder,
+  fn(user) { io.println("Processing: " <> user.name) }
+)
+```

docs/examples/schema_examples.md

@@ -0,0 +1,64 @@
+# Examples extracted from sparkling/src/sparkling/schema.gleam
+
+## FieldType examples
+
+```gleam
+UInt32
+Nullable(of: String)
+Array(of: Int32)
+Decimal(precision: 18, scale: 2)
+DateTime64(precision: 3)
+```
+
+## table/field examples
+
+```gleam
+table("users", [
+  field("id", UInt64),
+  field("email", String),
+  field("created_at", DateTime64(3)),
+])
+
+field("user_id", UInt64)
+field("name", Nullable(of: String))
+```
+
+## field_type_to_sql examples
+
+```gleam
+field_type_to_sql(UInt32)
+// => "UInt32"
+
+field_type_to_sql(Nullable(of: String))
+// => "Nullable(String)"
+
+field_type_to_sql(Array(of: Int32))
+// => "Array(Int32)"
+```
+
+## to_create_table_sql example
+
+```gleam
+let users_table = table("users", [
+  field("id", UInt64),
+  field("email", String),
+])
+
+to_create_table_sql(users_table, engine: "MergeTree()")
+// => "CREATE TABLE users (id UInt64, email String) ENGINE = MergeTree()"
+```
+
+## find_field / field_names examples
+
+```gleam
+let tbl = table("users", [field("id", UInt64)])
+find_field(tbl, "id")
+// => Some(Field("id", UInt64))
+
+find_field(tbl, "unknown")
+// => None
+
+let tbl = table("users", [field("id", UInt64), field("name", String)])
+field_names(tbl)
+// => ["id", "name"]
+```

docs/examples/types_examples.md

@@ -0,0 +1,32 @@
+# Examples extracted from sparkling/src/sparkling/types.gleam
+
+## Decimal examples
+
+```gleam
+let price = Decimal("123.45")
+let amount = Decimal("0.000001")
+```
+
+## DateTime64 example
+
+```gleam
+let timestamp = DateTime64("2024-01-15 10:30:45.123", 3, Some("UTC"))
+```
+
+## UUID example
+
+```gleam
+let id = UUID("550e8400-e29b-41d4-a716-446655440000")
+```
+
+## LowCardinality example
+
+```gleam
+let status = low_cardinality_string("active")
+```
+
+## Enum example
+
+```gleam
+let status = Enum8([#("active", 1), #("inactive", 2)])
+```

docs/quickstart.md

@@ -0,0 +1,39 @@
+# Quick Start
+
+This quick start shows a typical workflow using Sparkling's API in Gleam.
+
+```gleam
+import sparkling/query
+import sparkling/schema
+import sparkling/types
+
+// 1. Define your schema
+let users_table = schema.table("users", [
+  schema.field("id", schema.UInt32),
+  schema.field("name", schema.String),
+  schema.field("email", schema.String),
+  schema.field("created_at", schema.DateTime64),
+])
+
+// 2. Create a repository
+let repo = repo.new("http://localhost:8123")
+  |> repo.with_database("mydb")
+
+// 3. Build and execute queries
+let query = query.from(users_table)
+  |> query.select([expr.field("id"), expr.field("name")])
+  |> query.where_(expr.gt(expr.field("age"), expr.value("18")))
+  |> query.limit(10)
+
+// 4. Execute with repo
+let sql = query.to_sql(query)
+case repo.execute_sql(repo, sql) {
+  Ok(result) -> // parse result
+  Error(err) -> // handle error
+}
+```
+
+## Related examples
+- `docs/examples/schema_examples.md`
+- `docs/examples/types_examples.md`
+- `docs/examples/decode_examples.md`

gleam.toml

@@ -0,0 +1,25 @@
+name = "sparkling"
+version = "0.1.0"
+description = "A fast, type-safe ClickHouse client for Gleam with composable queries"
+licenses = ["Apache-2.0"]
+authors = ["Scaratti Daniele aka lupodevelp"]
+repository = { type = "github", user = "lupodevelop", repo = "sparkling" }
+links = [
+  { title = "GitHub", href = "https://github.com/lupodevelop/sparkling" }
+]
+#
+# For a full reference of all the available options, you can have a look at
+# https://gleam.run/writing-gleam/gleam-toml/.
+
+[dependencies]
+gleam_stdlib = ">= 0.34.0 and < 2.0.0"
+gleam_json = ">= 3.0.0 and < 4.0.0"
+gleam_http = ">= 4.0.0 and < 5.0.0"
+gleam_httpc = ">= 4.0.0 and < 5.0.0"
+gleam_erlang = "~> 1.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"
+
+[package]
+files = ["src", "README.md", "CHANGELOG.md", "LICENSE"]

manifest.toml

@@ -0,0 +1,19 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "gleam_erlang", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "1124AD3AA21143E5AF0FC5CF3D9529F6DB8CA03E43A55711B60B6B7B3874375C" },
+  { name = "gleam_http", version = "4.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_http", source = "hex", outer_checksum = "82EA6A717C842456188C190AFB372665EA56CE13D8559BF3B1DD9E40F619EE0C" },
+  { name = "gleam_httpc", version = "4.1.1", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_http", "gleam_stdlib"], otp_app = "gleam_httpc", source = "hex", outer_checksum = "C670EBD46FC1472AD5F1F74F1D3938D1D0AC1C7531895ED1D4DDCB6F07279F43" },
+  { name = "gleam_json", version = "3.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "874FA3C3BB6E22DD2BB111966BD40B3759E9094E05257899A7C08F5DE77EC049" },
+  { name = "gleam_stdlib", version = "0.65.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "7C69C71D8C493AE11A5184828A77110EB05A7786EBF8B25B36A72F879C3EE107" },
+  { name = "gleeunit", version = "1.9.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "DA9553CE58B67924B3C631F96FE3370C49EB6D6DC6B384EC4862CC4AAA718F3C" },
+]
+
+[requirements]
+gleam_erlang = { version = "~> 1.0" }
+gleam_http = { version = ">= 4.0.0 and < 5.0.0" }
+gleam_httpc = { version = ">= 4.0.0 and < 5.0.0" }
+gleam_json = { version = ">= 3.0.0 and < 4.0.0" }
+gleam_stdlib = { version = ">= 0.34.0 and < 2.0.0" }
+gleeunit = { version = ">= 1.0.0 and < 2.0.0" }

src/sparkling.gleam

@@ -0,0 +1,78 @@
+// Core imports (must come before re-exports)
+/// Sparkling - An Ecto-like data layer for ClickHouse in Gleam
+/// 
+/// This library provides a type-safe, composable API for working with ClickHouse:
+/// - Schema definitions with typed tables and fields
+/// - Query builder DSL for SELECT/INSERT operations
+/// - Repository pattern with HTTP transport
+/// - Encode/decode for multiple formats (JSONEachRow, TabSeparated, CSV)
+/// - Changeset validation pipeline
+/// - Support for complex ClickHouse types (Decimal, DateTime64, Array, Map, UUID, etc.)
+/// 
+/// Examples: docs/quickstart.md
+///
+/// # Main Modules
+/// 
+/// - `sparkling/schema` - Table and field definitions
+/// - `sparkling/expr` - SQL expression AST
+/// - `sparkling/query` - Query builder DSL
+/// - `sparkling/repo` - Repository with HTTP transport
+/// - `sparkling/encode` - Encoding to ClickHouse formats
+/// - `sparkling/decode` - Decoding from ClickHouse formats
+/// - `sparkling/changeset` - Validation pipeline
+/// - `sparkling/types` - Complex ClickHouse types (Decimal, DateTime64, etc.)
+/// - `sparkling/format` - Format handlers registry
+import sparkling/changeset
+import sparkling/expr
+import sparkling/format
+import sparkling/query
+import sparkling/repo
+import sparkling/schema
+import sparkling/types
+
+// Re-export main types for convenience
+pub type Repo =
+  repo.Repo
+
+pub type RepoError =
+  repo.RepoError
+
+pub type Query =
+  query.Query
+
+pub type Table =
+  schema.Table
+
+pub type Field =
+  schema.Field
+
+pub type FieldType =
+  schema.FieldType
+
+pub type Expr =
+  expr.Expr
+
+pub type Changeset(a) =
+  changeset.Changeset(a)
+
+pub type FormatHandler =
+  format.FormatHandler
+
+// Re-export common complex types
+pub type Decimal =
+  types.Decimal
+
+pub type DateTime64 =
+  types.DateTime64
+
+pub type UUID =
+  types.UUID
+
+pub type LowCardinality =
+  types.LowCardinality
+
+pub type Enum8 =
+  types.Enum8
+
+pub type Enum16 =
+  types.Enum16