Voltar

Referência Rápida

Context — todos os métodos

// Path params
ctx.Param("nome")              // string
ctx.ParamInt("id")             // (int, bool)

// Query string
ctx.Query("q")                 // string
ctx.QueryDefault("order","asc")// string com fallback
ctx.QueryInt("page", 1)        // int com fallback
ctx.QueryAll("tag")            // []string

// Respostas
ctx.JSON(status, v)
ctx.HTML(status, html)
ctx.Redirect(url, status)
ctx.Error(code)

// Dados internos
ctx.Set("chave", valor)
ctx.Get("chave")               // (any, bool)

// Acesso direto
ctx.Request                    // *http.Request
ctx.Writer                     // http.ResponseWriter
ctx.Params                     // map[string]string

ORM — todos os métodos

// Leitura
orm.FromDB[T](db).All()                          // ([]T, error)
orm.FromDB[T](db).Each(func(t *T) error {...})   // streaming, memória O(1)
orm.FromDB[T](db).First()                        // (*T, error) — sql.ErrNoRows se vazio
orm.FromDB[T](db).Last()                         // (*T, error) — ordenação invertida
orm.FromDB[T](db).Exists()                       // (bool, error)
orm.FromDB[T](db).Count()                        // (int64, error)
orm.FromDB[T](db).Sum("col")                     // (float64, error) — também Avg/Min/Max

// Filtros tipados (retornam *Query[T]) — preferidos: coluna validada
.WhereEq("col", val)          // col = ?      (também OrWhereEq)
.WhereNe("col", val)          // col <> ?
.WhereGt/.WhereGte/.WhereLt/.WhereLte("col", val)  // col >, >=, <, <= ?
.WhereLike("col", "%termo%")  // col LIKE ?   (também OrWhereLike)
.WhereNull("col") / .WhereNotNull("col")

// Filtros em SQL livre — nunca concatene valores na string, só em args
.Where("col = ?", val)        // idêntico a WhereSQL
.OrWhere("col = ?", val)      // idêntico a OrWhereSQL
.WhereIn("id", ids)           // expande slice em placeholders (máx. 5000 valores)
.Join("users", "users.id = posts.user_id")     // filtro por relação
.LeftJoin("users", "users.id = posts.user_id")
.OrderBy("col DESC", "id")    // múltiplas colunas — ou orm.Desc("col")/orm.Asc("col")
.Select("id", "titulo")       // restringe colunas do SELECT (padrão: *)
.Distinct()
.Limit(n)
.Offset(n)

// Relações (carregamento sem N+1)
orm.Prefetch[Comentario](db, "post_id", ids, func(c *Comentario) int64 { return c.PostID })
// → (map[int64][]Comentario, error)

// Paginação
orm.FromDB[T](db).Where(...).OrderBy("id DESC").Paginate(page, 20)     // pageSize máx. 1000
orm.FromDB[T](db).OrderBy("id DESC").PaginateNoCount(page, 20)         // sem COUNT(*)
// → (Page[T], error)
// Page[T]: Items, Total, Page, PageSize, TotalPages, HasNext, HasPrev

orm.FromDB[T](db).PaginateAfter("id", cursor, false, 20) // keyset — custo não cresce com a página
// → (KeysetPage[T], error) — KeysetPage[T]: Items, NextCursor, HasNext

// Escrita
orm.Create(db, &model)                         // error — preenche PK
orm.CreateAll(db, []*T{...})                   // bulk: um INSERT multi-VALUES
orm.FromDB[T](db).Where(...).Update(map[string]any{...}) // error
orm.FromDB[T](db).Where(...).Delete()            // error
orm.FromDB[T](db).Where(...).GetOrCreate(&defaults)      // (*T, created, error) — recupera de corrida via UNIQUE
orm.FromDB[T](db).Where(...).UpdateOrCreate(values, &defaults) // (created, error) — idem

// Transações (atômico — commit/rollback automático)
fw.DB.Use().Transaction(func(tx *database.Tx) error {
    orm.CreateTx(tx, &model)
    return orm.FromTx[T](tx).Where(...).Update(...)
})

// Multi-tenant
db := fw.DB.Use().WithSchema("tenant_abc")
orm.FromDB[T](db).All()  // → SELECT * FROM tenant_abc.tabela

ORM — tags do model

Tag	Efeito
kyrux:"pk"	Chave primária — ignorado no INSERT, preenchido após criação
kyrux:"column:nome"	Override do nome da coluna SQL
kyrux:"size:N"	VARCHAR(N) no makemigrations
kyrux:"unique"	CREATE UNIQUE INDEX no makemigrations (apenas migration)
kyrux:"default:valor"	Valor SQL literal no INSERT se campo for zero Go
kyrux:"hash"	Hash Argon2id+pepper automático na escrita; nunca revertido
kyrux:"encrypt"	AES-256-GCM: cifra na escrita, decifra na leitura
kyrux:"login"	Exclusivo do auth.User — define o campo de login; imutável após migrate
kyrux:"autonow"	CURRENT_TIMESTAMP automático em todo Update; preenche no Create se zerado
kyrux:"fk:tabela"	REFERENCES tabela(id) + índice na migration

Auth — todos os métodos

// Model
user.SetPassword("senha")          // hash Argon2id + pepper
user.CheckPassword("senha")        // bool
user.FullName()                    // "Nome Sobrenome"

// Campo de login (determinado pela tag kyrux:"login" no model User)
auth.LoginFieldName()                              // string — "Username" ou "Email"

// SSR (sessão)
auth.Login(db, store, w, r, loginValue, password)  // (*session.Session, error)
auth.Logout(store, r, w)                           // remove sessão + expira cookie
auth.GetUser(db, store, r)                         // (*User, error)
auth.NextURL(r, fallback)                          // string — lê ?next=, valida open redirect

// JWT
fw.Auth.GenerateToken(userID, ttl)  // (string, error)
fw.Auth.ValidateToken(token)        // (*Claims, error)

// Erros SSR
auth.ErrUserNotFound
auth.ErrWrongPassword
auth.ErrInactiveUser
auth.ErrAuthDisabled  // retornado quando DB_ENABLED=false

Realtime — todos os métodos

fw.Realtime.Replace("target", html)   // innerHTML = html
fw.Realtime.Append("target", html)    // adiciona ao final
fw.Realtime.Prepend("target", html)   // adiciona ao início
fw.Realtime.Remove("target")          // remove o elemento
fw.Realtime.Broadcast("evento", data) // publica no EventBus

EventBus — todos os métodos

fw.Events.Subscribe("evento", handler)   // assinar
fw.Events.Publish("evento", payload)     // publicar
fw.Events.Unsubscribe("evento")          // cancelar

DB Manager — todos os métodos

fw.DB.Add("nome", "driver", "dsn")          // adicionar conexão
fw.DB.Use()                                 // conexão "default"
fw.DB.Use("nome")                           // conexão nomeada
fw.DB.Use().WithSchema("schema")            // cópia com schema (multi-tenant)
fw.DB.Use().Transaction(func(tx) error { ... })
fw.DB.Close()                               // encerrar todas

Render — funções globais e processors

// Funções customizadas para templates (disponíveis globalmente)
render.AddFunc("nome", funcao)
render.AddFunc("formatarData", func(t time.Time) string {
    return t.Format("02/01/2006")
})

// ContextProcessors — variáveis injetadas em todos os templates de todos os apps
render.AddDefaultProcessor(func(ctx *router.Context) map[string]any {
    return map[string]any{"ano": time.Now().Year()}
})

// Renderizar fragmento para string (usado com Realtime)
html, err := render.Partial("appName", "partials/lista.html", data)

Crypton — utilitários de segurança

// Setup (chamado pelo bootstrap automaticamente)
crypton.SetPepper(pepper)
crypton.SetEncryptionKey(key)

// Senhas (Argon2id — formato PHC)
crypton.HashPassword("senha")                  // (string, error) — $argon2id$...
crypton.CheckPassword("senha", hash)           // bool — comparação em tempo-constante

// Criptografia simétrica (AES-256-GCM)
crypton.Encrypt("dado sensível")               // (string, error) — $enc$<base64>
crypton.Decrypt("$enc$<base64>")              // (string, error)

// Assinatura HMAC-SHA256
crypton.Sign("payload", "secret")             // (string, error) — <b64>.<sig>
crypton.Verify("token", "secret")             // (string, error) — payload ou erro

// Aleatoriedade criptograficamente segura
crypton.RandomBytes(32)                        // ([]byte, error)

Errors — customização de páginas de erro

import kyerrors "kyrux/core/errors"

// Registrar handler customizado para código HTTP
kyerrors.Set(404, func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(404)
    json.NewEncoder(w).Encode(map[string]string{"error": "não encontrado"})
})

kyerrors.Set(500, func(w http.ResponseWriter, r *http.Request) {
    // renderizar template personalizado de erro 500
})

Handlers registrados têm prioridade sobre o comportamento padrão em qualquer ambiente.

Session — API de baixo nível

import "kyrux/core/security/session"

// Criar sessão manualmente
sess, err := fw.Sessions.New()
sess.Set("chave", valor)
session.SetCookie(ctx.Writer, sess.ID, ctx.Request.TLS != nil)

// Ler sessão do request
sess, ok := session.FromRequest(ctx.Request, fw.Sessions)
if !ok { /* sem sessão */ }

// Acessar valores (seguro para requisições paralelas)
val, ok := sess.Get("chave")

// Encerrar sessão
fw.Sessions.Delete(sess.ID)

---

Kyrux — execução no momento certo. Desenvolvido por Müller Nocciolli · Licença MIT com atribuição obrigatória.