pure-schemify 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### What's Changed
+
+- **Documentation**: Created `README.md` to explain the library's purpose, implementation details, and usage.
+- **Configuration**: Added `.gitignore` to maintain a clean repository.
+- **Initial Commit**: documented existing source code.

package/README.md

@@ -0,0 +1,153 @@
+# purecore-schemify
+
+**purecore-schemify** is a **High Fidelity Polyfill** for Zod-like schema validation, designed specifically for the `@purecore` ecosystem. It provides a lightweight, zero-dependency, type-safe runtime validation library that follows the fluent API design pattern familiar to TypeScript developers.
+
+This library allows you to define schemas for your data, infer TypeScript types automatically, and validate data at runtime with informative error reporting.
+
+## 🚀 Features
+
+- **Zero Dependencies**: Built entirely with native TypeScript, ensuring minimal footprint and maximum portability.
+- **Fluent API**: Chainable methods (e.g., `.min()`, `.optional()`, `.refine()`) for intuitive schema definition.
+- **Static Type Inference**: Automatic TypeScript type inference using `z.infer<typeof schema>`.
+- **Runtime Validation**: Robust `parse` and `safeParse` methods to ensure data integrity.
+- **Nominal Typing Support**: Built-in support for Nominal Types via `z.nominal` and atomic behaviors, enforcing strict domain modeling.
+- **Extensible**: check mechanisms, refinements, and transformations.
+
+## 📦 Installation
+
+Since this is part of the `@purecore` monorepo structure, you can typically use it by importing the source directly or linking the package.
+
+```bash
+bun install @purecore/schemify
+```
+
+_(Note: Adjust installation method based on your specific workspace configuration)_
+
+## 🛠 Usage
+
+### Basic Primitives
+
+```typescript
+import { z } from "./src/index";
+
+// String Schema
+const emailSchema = z.string().email().min(5);
+
+// Number Schema
+const ageSchema = z.number().int().min(18).max(120);
+
+// Parse
+emailSchema.parse("user@example.com"); // "user@example.com"
+ageSchema.parse(25); // 25
+```
+
+### Object Schemas
+
+```typescript
+const UserSchema = z.object({
+  id: z.number(),
+  username: z.string().min(3),
+  isActive: z.boolean().default(true),
+  roles: z.array(z.string()).optional(),
+});
+
+type User = z.infer<typeof UserSchema>;
+// inferred as: { id: number; username: string; isActive: boolean; roles?: string[] }
+
+const result = UserSchema.safeParse({
+  id: 1,
+  username: "alice",
+});
+
+if (result.success) {
+  console.log(result.data);
+} else {
+  console.error(result.error);
+}
+```
+
+## 🧠 Advanced Concepts: Nominal & Atomic Types
+
+One of the unique features of `purecore-schemify` is its first-class support for **Nominal Types** and **Atomic Behaviors**. This allows you to create opaque types that are structurally strings/numbers but semantically distinct.
+
+### Behaviors
+
+```typescript
+// Define a behavior for a UserID
+const UserId = z.behavior("UserId", z.string().uuid());
+
+// Forge a value (validates and brands it)
+const id = UserId.forge("123e4567-e89b-12d3-a456-426614174000");
+
+// 'id' is now typed as AtomicType<string, "UserId">
+// It cannot be accidentally assigned to a generic string or another nominal type.
+```
+
+### Nominal Wrapper
+
+```typescript
+const Email = z.nominal("Email", z.string().email());
+
+const myEmail = Email.validate("test@test.com");
+```
+
+## 📚 Technical Deep Dive: How it Works
+
+### The Core: `SchemifyType`
+
+At the heart of the library is the abstract base class `SchemifyType<Output, Def, Input>`.
+
+- **`_parseSync`**: Every specific type (String, Number, Object) implements this abstract method to perform its core validation logic.
+- **`_process`**: This method handles the common logic for all types:
+  1.  **Optional/Nullable/Default**: Checks if the value is missing or null and handles it based on configuration.
+  2.  **Validation**: Calls `_parseSync`.
+  3.  **Refinements**: Executes custom `.refine()` checks.
+  4.  **Transforms**: Applies `.transform()` functions to modify the output.
+
+### The Facade: `z`
+
+The `z` export acts as a singleton factory. It provides convenient accessors to instantiate specific `SchemifyType` subclasses (`SchemifyString`, `SchemifyObject`, etc.), mimicking the API surface of popular validation libraries for ease of adoption.
+
+### Error Handling
+
+Errors are aggregated into a `SchemifyError` class, which contains an array of `SchemifyIssue` objects. Each issue pinpoints the `path` (e.g., `user.address.street`) and the `code` of the error, allowing for precise UI feedback (like form validation errors).
+
+## 🧪 How to Test
+
+You can test the library using `bun test` or by running a simple script to verify behavior.
+
+**Example Test Script (`test.ts`):**
+
+```typescript
+import { z } from "./src/index";
+
+const schema = z.object({
+  name: z.string(),
+  age: z.number().min(0),
+});
+
+try {
+  const data = schema.parse({ name: "Bob", age: 30 });
+  console.log("✅ Validation passed:", data);
+} catch (e) {
+  console.error("❌ Validation failed:", e);
+}
+
+try {
+  schema.parse({ name: "Bob", age: -5 });
+} catch (e) {
+  console.log("✅ Expected failure caught:", e.message);
+}
+```
+
+Run it with:
+
+```bash
+wsl bun run test.ts
+```
+
+---
+
+_Created by Antigravity for the @purecore open-source initiative._
+
+[View Changelog](./CHANGELOG.md)

package/TODO.md

@@ -0,0 +1,238 @@
+
+**Contexto**
+Você é um agente de codificação encarregado de **inferir tipos semânticos atômicos** a partir de código TypeScript existente que hoje usa apenas **primitivos** (`boolean`, `number`, `string`, `Date`). Não assuma bibliotecas externas instaladas. Seu objetivo é:
+
+1. detectar candidatos a **tipos semânticos**;
+2. propor **nomes canônicos** no padrão `dominio.entidade.nome` (com ponto);
+3. sugerir **regras e validações** mínimas;
+4. gerar **artefatos** auto-contidos (sem dependências externas);
+5. listar **até 5 novos tipos** que ainda **não existem** no repositório e que valem a pena padronizar. 
+5. listar **até 5 novos tipos** que ainda **não existem** no repositório e que valem a pena padronizar, que sejam os mais específicos daquele domínio e/ou entidade.
+
+> Use linguagem e comentários em **português**.
+
+---
+
+## Entradas que você tem
+
+* Árvore de arquivos `.ts/.tsx` e testes.
+* Nomes de variáveis, propriedades, funções, schemas, migrações, seeds.
+* Strings literais, sufixos/prefixos, nomes de colunas/IDs e chamadas de API.
+
+---
+
+## Saídas obrigatórias (em ORDEM)
+
+1. **Relatório** em Markdown: achados, suposições e conflitos.
+2. **Manifesto** `semantic-types.manifest.json` com as inferências.
+3. **Stubs** de tipos canônicos (arquivos `.ts` auto-contidos).
+4. **Patches** (diff unificado) mostrando como aplicar os tipos.
+5. **Roadmap** com até **5** tipos novos recomendados (ainda não mapeados).
+
+---
+
+## Padrão de Nomes (canônicos)
+
+Use `kebab` no arquivo e **ponto** no AtomicType:
+
+* Arquivo: `domains/{Domain}/{Entity}/{name}.ts`
+* AtomicType interno: `{domain}.{entity}.{name}`
+  Ex.: `domains/ecommerce/order/total.ts` → AtomicType `ecommerce.order.total`.
+
+---
+
+## Heurísticas de Inferência
+
+### A) Booleans
+
+Detecção por **prefixos** e contexto de uso:
+
+* `is*`, `has*`, `can*`, `should*`, `enable*`, `allow*`, `show*`
+* Exemplos canônicos:
+
+  * `isDone` → `project.task.isDone`
+  * `hasAllergies` → `health.patient.hasAllergies`
+  * `showWeekViewCalendar` → `ui.calendar.showWeekView`
+    Valide: coação para boolean, proibir `null/undefined` (ou explicitar `Maybe`), e **combinadores** só via funções (`and`, `or`) — nunca `&&` direto entre AtomicTypes.
+
+### B) Numbers
+
+Use nomes, unidades, e padrões:
+
+* Sufixos/palavras-chave: `total`, `amount`, `price`, `quantity`, `count`, `size`, `capacity`, `rate`, `percentage`, `score`, `weight`, `length`, `height`, `width`, `radius`, `duration`.
+* Padrões literais: `%`, `ms`, `s`, `min`, `h`, `kg`, `g`, `m`, `cm`, `km`, `px`, `rem`, `brl`, `usd`.
+* Exemplos:
+
+  * `totalAppointments` → `clinic.schedule.totalAppointments` (inteiro ≥ 0)
+  * `revenueTotal` → `ecommerce.order.revenueTotal.brl` (moeda BRL)
+  * `teethExtracted` → `dentistry.procedure.teethExtracted` (inteiro 0–32)
+  * `percentage` → `metrics.kpi.percentage` (0–100 ou 0–1 — explicitar escala)
+  * `durationMs` → `time.duration.ms`
+    Valide: **faixas** (min/max), **inteireza** quando nome implicar contagem, e **unidade** no nome canônico (ex.: `.brl`, `.usd`, `.kg`, `.ms`).
+
+### C) Strings
+
+Detecte **formatos**:
+
+* `email`, `phone`, `url`, `slug`, `isoCode`, `cpf/cnpj`, `uuid`, `id` (se houver padrão).
+* Regex úteis (documente no stub):
+
+  * Email (robusto suficiente): `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`
+  * URL: usar `new URL()` no validador (cair no catch se inválida)
+  * UUID v4: `/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i`
+* Exemplos:
+
+  * `customerEmail` → `crm.customer.email`
+  * `orderId` (uuid) → `ecommerce.order.id`
+  * `countryIso2` → `geo.country.iso2`
+
+### D) Date/Tempo
+
+Mapeie granularidade: `createdAt`, `updatedAt`, `startAt`, `endAt`, `birthday`, `scheduledFor`, `dueAt`.
+
+* Exemplos:
+
+  * `scheduledFor` → `calendar.event.scheduledAt` (Date)
+  * `birthday` → `identity.person.birthDate` (Date sem hora — normalize)
+
+---
+
+## Sem biblioteca externa? Forneça **Shim** local (TS puro)
+
+Crie **um** utilitário interno para os Atomic Behavior Types de Semânticos **sem runtime**:
+
+```ts
+// src/AtomicBehaviorTypes/forge.ts
+declare const __AtomicType: unique symbol;
+
+export type AtomicType<T, Name extends string> = T & { readonly [__AtomicType]: Name };
+
+export function BehaviorType<Name extends string>() {
+  return {
+    of: <T>(v: T) => v as AtomicType<T, Name>,
+    un: <T>(v: AtomicType<T, Name>) => v as unknown as T,
+  };
+}
+```
+
+
+## Facilitando a Instanciação com Funções 'forge'
+
+Para tornar a criação de tipos semânticos mais intuitiva e menos verbosa, recomenda-se adicionar funções auxiliares simples, conhecidas como "forgers" ou "factories", diretamente nos módulos de cada tipo. Essas funções permitem instanciações rápidas, como `forgeEmail('sussu@gmail.com')`, evitando a necessidade de chamar métodos mais complexos como `Email.of(...)` em contextos cotidianos.
+
+
+### Por que Usar Funções 'forge'?
+
+- **Simplicidade:** Reduz a curva de aprendizado e o boilerplate, especialmente em código de produção onde a validação já é implícita.
+- **Legibilidade:** Torna o código mais declarativo, focando no valor em vez da construção do tipo.
+- **Compatibilidade:** Pode coexistir com as funções existentes (como `of` e `un`), servindo como atalhos para casos comuns.
+- **Aplicação Gradual:** Facilita a migração de primitivos para tipos semânticos sem quebrar o fluxo de desenvolvimento.
+
+
+### Recomendações
+
+- **Padronização:** Sempre inclua `forge` em novos tipos para promover adoção rápida.
+- **Validação:** A função `forge` deve herdar as validações de `of`, garantindo consistência.
+- **Documentação:** No README de cada domínio, exemplifique usos com `forge` para onboarding.
+- **Evolução:** Se necessário, expanda `forge` com overloads para aceitar múltiplos formatos (ex.: `forge` para datas aceitando string ou timeBehaviorType).
+
+Essa abordagem torna os tipos semânticos mais acessíveis, acelerando a migração e reduzindo erros em projetos reais.
+
+
+### Como Implementar
+
+Adicione uma função `forge` em cada stub de tipo, que internamente chame a função `of` existente. Isso mantém a validação e o AtomicTypeing, mas oferece uma interface mais amigável.
+
+#### Exemplo para Boolean (ex.: `project.task.isDone`)
+
+```ts
+// domains/project/task/is-done.ts
+import { AtomicType, BehaviorType } from "../../src/AtomicBehaviorTypes/forge";
+export type IsDone = AtomicType<boolean, "project.task.isDone">;
+
+export const IsDone = (() => {
+  const f = BehaviorType<"project.task.isDone">();
+  return {
+    of: (v: unknown): IsDone => f.of(Boolean(v)),
+    un: (v: IsDone): boolean => f.un(v),
+    and: (a: IsDone, b: IsDone): IsDone => f.of(f.un(a) && f.un(b)),
+    forge: (value: boolean): IsDone => f.of(value),
+  };
+})();
+```
+Uso: `const isCompleted = IsDone.forge(true);` (equivalente a `IsDone.of(true)`).
+
+### Number com moeda (ex.: `ecommerce.order.revenueTotal.brl`)
+
+```ts
+// domains/ecommerce/order/revenue-total.brl.ts
+import { AtomicType, BehaviorType } from "../../src/AtomicBehaviorTypes/forge";
+export type RevenueTotalBRL = AtomicType<number, "ecommerce.order.revenueTotal.brl">;
+
+export const RevenueTotalBRL = (() => {
+  const f = BehaviorType<"ecommerce.order.revenueTotal.brl">();
+  return {
+    of: (v: unknown): RevenueTotalBRL => {
+      const n = Number(v);
+      if (!Number.isFinite(n) || n < 0) throw new TypeError("revenue must be >= 0");
+      return f.of(n);
+    },
+    un: (v: RevenueTotalBRL) => f.un(v),
+    add: (a: RevenueTotalBRL, b: RevenueTotalBRL): RevenueTotalBRL => f.of(f.un(a) + f.un(b)),
+    forge: (value: number): RevenueTotalBRL => f.of(value),  // Nova função forge
+  };
+})();
+```
+
+### String formatada (ex.: `crm.customer.email`)
+
+```ts
+// domains/universal/user/email.ts
+import { AtomicType, BehaviorType } from "../../src/AtomicBehaviorTypes/forge";
+export type Email = AtomicType<string, "crm.customer.email">;
+
+export const Email = (() => {
+  const f = BehaviorType<"crm.customer.email">();
+  const emailRx = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return {
+    of: (v: unknown): Email => {
+      const s = String(v).trim();
+      if (!emailRx.test(s)) throw new TypeError("invalid email");
+      return f.of(s);
+    },
+    un: (v: Email) => f.un(v),
+    forge: (value: string): Email => f.of(value),
+  };
+})();
+```
+
+### Date (ex.: `calendar.event.scheduledAt`)
+
+```ts
+// domains/calendar/event/scheduled-at.ts
+import { AtomicType, BehaviorType } from "../../src/AtomicBehaviorTypes/forge";
+export type ScheduledAt = AtomicType<Date, "calendar.event.scheduledAt">;
+
+export const ScheduledAt = (() => {
+  const f = BehaviorType<"calendar.event.scheduledAt">();
+  return {
+    of: (v: unknown): ScheduledAt => {
+      const d = v instanceof Date ? v : new Date(String(v));
+      if (Number.isNaN(d.getTime())) throw new TypeError("invalid date");
+      return f.of(d);
+    },
+    un: (v: ScheduledAt) => f.un(v),
+    forge: (value: string | Date): ScheduledAt => f.of(value),
+  };
+})();
+```
+
+
+
+## Regras de qualidade que o agente deve aplicar
+
+* **Nunca** substituir primitivo por tipo semântico sem **stub** + **import**.
+* Apontar ambiguidade (`rate`, `size`, `code`) e sugerir **AtomicType** com **unidade ou domínio** explícitos.
+* Sugerir **faixas**: contagens (≥ 0), porcentagens (0–1 ou 0–100 — escolha e documente).
+* Não criar tipos transdomínio: `ecommerce.*` não reage com `crm.*` (a menos que o projeto já defina).
+* Se detectar `any` em locais críticos, abrir **nota** para migração gradual com marcas semânticas.

package/dist/healer.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Core Healer Library
+ * Uma biblioteca para validação e "cura" automática de tipos de dados.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.healAndValidate = exports.Strategy = exports.Reflector = exports.Pharmacy = void 0;
+// --- 1. Pharmacy: Encapsula o conhecimento de conversão de tipos ---
+// Responsável por saber como transformar um tipo "A" num tipo "B".
+exports.Pharmacy = {
+    /** Dicionário de "vacinas" (conversões) disponíveis */
+    vaccines: {
+        string: (value) => ({
+            to: {
+                number: !isNaN(parseFloat(value)) && isFinite(value)
+                    ? Number(value)
+                    : undefined,
+                boolean: value.toLowerCase() === "true"
+                    ? true
+                    : value.toLowerCase() === "false"
+                        ? false
+                        : undefined,
+            },
+        }),
+        number: (value) => ({
+            to: {
+                string: String(value),
+            },
+        }),
+        boolean: (value) => ({
+            to: {
+                number: value ? 1 : 0,
+                string: String(value),
+            },
+        }),
+    },
+    /**
+     * Tenta administrar uma conversão de tipo segura.
+     * @returns O valor convertido ou undefined se não houver conversão disponível.
+     */
+    administer: (value, fromType, toType) => {
+        try {
+            return exports.Pharmacy.vaccines[fromType]?.(value).to[toType];
+        }
+        catch {
+            return undefined;
+        }
+    },
+};
+// --- 2. Reflector: Lida com a introspecção de tipos ---
+exports.Reflector = {
+    /** Obtém a estrutura actual do payload com os seus tipos */
+    getStructure: (obj) => Object.entries(obj).map(([key, value]) => [key, typeof value]),
+    /** Obtém o tipo alvo definido no esquema para uma determinada chave */
+    getTargetType: (schema, key) => {
+        const target = schema[key];
+        // Se o esquema define um valor padrão em vez de uma string de tipo
+        return typeof target === "string" &&
+            ["string", "number", "boolean"].includes(target)
+            ? target
+            : typeof target;
+    },
+};
+// --- 3. Strategy: Gere as transições de estado e recursão ---
+exports.Strategy = {
+    /** Verifica se o limite de tentativas de cura foi atingido */
+    isLimitReached: (rounds, limit) => rounds >= limit,
+    /** Prepara o próximo contexto com o valor "curado" */
+    prepareNextAttempt: (ctx, key, healedValue) => ({
+        ...ctx,
+        payload: { ...ctx.payload, [key]: healedValue },
+        rounds: (ctx.rounds || 0) + 1,
+    }),
+};
+// --- 4. Logic: Redutor de Validação e Processamento ---
+const processField = (ctx) => (failures, [key, currentType]) => {
+    const targetType = exports.Reflector.getTargetType(ctx.schema, key);
+    // Caso de Sucesso: Os tipos coincidem
+    if (currentType === targetType)
+        return failures;
+    // Caso de Cura: Tenta converter o valor
+    const healedValue = exports.Pharmacy.administer(ctx.payload[key], currentType, targetType);
+    // Verifica se a cura foi bem-sucedida E se o novo payload passa na validação (recursão)
+    const isFixed = healedValue !== undefined &&
+        (0, exports.healAndValidate)({
+            ...exports.Strategy.prepareNextAttempt(ctx, key, healedValue),
+        });
+    if (!isFixed) {
+        failures.push([key, currentType]);
+    }
+    else {
+        // Aplica a cura no payload do contexto actual (mutação controlada para o resultado final)
+        ctx.payload[key] = healedValue;
+    }
+    return failures;
+};
+// --- 5. Ponto de Entrada Principal ---
+/**
+ * Tenta validar e curar um payload baseando-se num esquema.
+ * @param ctx Contexto contendo o payload e o esquema alvo.
+ * @returns Verdadeiro se o payload estiver válido (ou foi curado com sucesso).
+ */
+const healAndValidate = (ctx) => {
+    const { rounds = 0, LIMIT = 3, payload } = ctx;
+    if (exports.Strategy.isLimitReached(rounds, LIMIT))
+        return false;
+    const failures = exports.Reflector.getStructure(payload).reduce(processField(ctx), []);
+    return failures.length === 0;
+};
+exports.healAndValidate = healAndValidate;