{"id":32623443,"url":"https://github.com/mtctx/zappy","last_synced_at":"2025-10-30T19:57:14.342Z","repository":{"id":321486893,"uuid":"1085329826","full_name":"mtctx/Zappy","owner":"mtctx","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-29T22:19:11.000Z","size":119,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-29T23:37:42.997Z","etag":null,"topics":["annotation-processing","compile-time","data-generation","declarative","fake-data","faker","kotlin","kotlin-library","ksp","mock","test-automation","testing","type-safe","zappy-pattern-language","zpl"],"latest_commit_sha":null,"homepage":"http://zappy.apidoc.mtctx.dev/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtctx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-28T22:25:29.000Z","updated_at":"2025-10-29T22:21:57.000Z","dependencies_parsed_at":"2025-10-29T23:47:53.264Z","dependency_job_id":null,"html_url":"https://github.com/mtctx/Zappy","commit_stats":null,"previous_names":["mtctx/zappy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mtctx/Zappy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtctx%2FZappy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtctx%2FZappy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtctx%2FZappy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtctx%2FZappy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtctx","download_url":"https://codeload.github.com/mtctx/Zappy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtctx%2FZappy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281873515,"owners_count":26576262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation-processing","compile-time","data-generation","declarative","fake-data","faker","kotlin","kotlin-library","ksp","mock","test-automation","testing","type-safe","zappy-pattern-language","zpl"],"created_at":"2025-10-30T19:56:46.607Z","updated_at":"2025-10-30T19:57:14.334Z","avatar_url":"https://github.com/mtctx.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zappy – Declarative Mock Data for Kotlin\n\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Kotlin](https://img.shields.io/badge/Kotlin-2.2.21-blue.svg)](https://kotlinlang.org)\n[![KSP](https://img.shields.io/badge/KSP-2.3.0-orange.svg)](https://github.com/google/ksp)\n[![Maven Central Core](https://img.shields.io/maven-central/v/dev.mtctx.library/zappy-core?label=Maven%20Central%20Core)](https://central.sonatype.com/artifact/dev.mtctx.library/zappy-core)\n[![Maven Central Processor](https://img.shields.io/maven-central/v/dev.mtctx.library/zappy-processor?label=Maven%20Central%20Processor)](https://central.sonatype.com/artifact/dev.mtctx.library/zappy-processor)\n\n---\n\n## What is Zappy?\n\n**Zappy** is a **KSP-powered**, **zero-reflection**, **type-safe** mock data generator for Kotlin.\n\nAnnotate your data classes with `@Mock` and fields with ZPL-aware annotations (`@Name`, `@Email`, etc.), then generate\nfully-populated instances with a single call:\n\n```kotlin\nval user = mock\u003cUser\u003e()\n```\n\nNo boilerplate. No reflection. No runtime cost.\n\n---\n\n## Modules\n\n| Module              | Description                                                                            |\n|---------------------|----------------------------------------------------------------------------------------|\n| **zappy-core**      | Core ZPL engine, annotations, built-in providers, and `String.generateWithZPL()`       |\n| **zappy-processor** | KSP annotation processor that generates `mock\u003cT\u003e()` and `mock_X_Y_Z_Class()` functions |\n| **zappy-test**      | Example usage tests                                                                    |\n\n---\n\n## Features\n\n* **Annotation-Driven**: `@Mock` on classes, `@Name`, `@Email`, etc. on fields\n* **ZPL (Zappy Pattern Language)**: Declarative fake data via `\u003cpattern\u003e` strings\n* **Length Control**: `\u003cusername:5-12\u003e`, `\u003cnumeric:1-100\u003e`, etc.\n* **Extensible**: Add custom `ZPLProvider`s and annotations\n* **Compile-Time Code Gen**: No reflection, zero runtime overhead\n* **Kotlin-First**: Pure Kotlin, no Java dependencies\n* **GPL-3.0 Licensed** with full SPDX compliance\n\n---\n\n## Installation\n\nZappy is published to **Maven Central**.\n\n### Gradle (Kotlin DSL)\n\n```kotlin\nplugins {\n    id(\"com.google.devtools.ksp\") version \"1.9.20-1.0.14\"\n}\n\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    implementation(\"dev.mtctx.library:zappy-core:1.1.0\")\n    ksp(\"dev.mtctx.library:zappy-processor:1.1.0\")\n}\n```\n\n\u003e **Important**: KSP must be applied for the processor to run.\n\n---\n\n## Example Usage\n\n```kotlin\nimport dev.mtctx.zappy.mock\n\n@Mock\ndata class User(\n    @Name val username: String,\n    @Email val email: String,\n    @Numeric(\":1-2\") val age: Int // 1-2 digits, e.g. 1, 2, ... 12, 35, ...\n)\n\nfun main() {\n    val user = mock\u003cUser\u003e()\n    println(user)\n    // → User(username=7g1iH7VlMBM2C, email=7g1iH7VlMBM2C@example.io, age=42)\n}\n```\n\n\u003e Output is **fully random** — no fixed examples like \"alice@example.com\".\n\n---\n\n## Documentation\n\n### How to Create a Mockable Class\n\n```kotlin\n@Mock\ndata class Profile(\n    @Name val username: String,\n    @Email val email: String,\n    @ISODate val createdAt: String,\n)\n```\n\n* Use `@Mock` on the class\n* Use ZPL annotations on fields\n* Default ZPL strings are provided (e.g. `\u003cusername\u003e`)\n* Call `mock\u003cProfile\u003e()` anywhere\n\n\u003e **Important**: Every type has to be a String, or else the processor won't work. Will be fixed in the future.\n\n---\n\n### How to Create a Custom Annotation\n\n```kotlin\n@ZappyAnnotation\n@Retention(AnnotationRetention.SOURCE)\n@Target(AnnotationTarget.FIELD)\nannotation class FullName(val zpl: String = \"\u003cusername\u003e_\u003cnumeric:1-99\u003e\")\n\n@Mock\ndata class Person(\n    @FullName val fullName: String\n)\n```\n\n\u003e `@ZappyAnnotation` enables KSP processing.  \n\u003e Must have a `zpl: String` parameter.\n\n---\n\n### How to Create a Custom ZPLProvider\n\n```kotlin\nobject CreditCardZPLProvider : ZPLProvider() {\n    override val id: String = \"credit-card\" // will be used as \"\u003ccredit-card\u003e\"\n    override val characterList = ('0'..'9').toList()\n\n    override fun generate(minLength: Int, maxLength: Int): String {\n        val digits = length(minLength, maxLength).map { characterList.random() }.joinToString(\"\")\n        return digits.chunked(4).joinToString(\"-\")\n    }\n}\n\n// Register when using mock (e.g., in main or Application class)\nmock\u003cPerson\u003e(CreditCardZPLProvider)\n```\n\nNow use: `\u003ccredit-card:19\u003e` → `\"1234-5678-9012-3456\"`\n\n---\n\n### How to Use ZPL Directly\n\n```kotlin\nval pattern = \"\u003cusername:5-10\u003e@\u003cdomain\u003e\"\nval email = pattern.generateWithZPL()\n\nprintln(email) // → \"a1b2c@example.com\"\n```\n\n* Use any registered provider\n* Combine providers: `\u003cemail\u003e`, `\u003cuuid\u003e`, custom ones\n* Length control: `:min-max`, `:min`, `:-max`\n\n---\n\n## Built-in ZPL Providers\n\n| ID                       | Example Output                         |\n|--------------------------|----------------------------------------|\n| `\u003cname\u003e`                 | `k9PxM2vN`                             |\n| `\u003cemail\u003e`                | `Bc34QQ6grdHQ0ozz@2noJRHYKqklOFZ.com`  |\n| `\u003cdomain\u003e`               | `aa2fa5.net`                           |\n| `\u003cnumeric\u003e`              | `42`                                   |\n| `\u003cpassword\u003e`             | `e*\u003cPyXvp]B`                           |\n| `\u003ctoken\u003e`                | `YWEeWGC3Fd4Fk-H`                      |\n| `\u003cuuid\u003e`                 | `f47ac10b-58cc-4372-a567-0e02b2c3d479` |\n| `\u003ciso-date\u003e (Base Only)` | `2025-10-29T14:30:22Z`                 |\n| `\u003cphone-number\u003e`         | `+1017079879685250`                    |\n| `\u003curl\u003e`                  | `http://2ikEu.io`                      |\n\n\u003e **Note**: `\u003ciso-date\u003e` requires a custom provider. See [Custom ZPLProvider](#how-to-create-a-custom-zplprovider).\n\n---\n\n## Documentation\n\nFull API reference (Dokka):  \n[https://zappy.apidoc.mtctx.dev](https://zappy.apidoc.mtctx.dev)\n\n---\n\n## Contributing\n\nContributions are **very welcome**!  \nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).\n\n---\n\n## License\n\nZappy is **free software** under the **GNU GPL v3**.  \nYou can use, modify, and distribute it — as long as it remains free.\n\nCopyright (C) 2025 mtctx\n\n---\n\n\u003e **Zappy: Fake data, real fast.**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtctx%2Fzappy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtctx%2Fzappy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtctx%2Fzappy/lists"}