implementado filtro Delta

dist-back/filtroDelta.js

@@ -28,6 +28,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var filtroDelta_exports = {};
 __export(filtroDelta_exports, {
+  iniciarFiltroDelta: () => iniciarFiltroDelta,
+  operadorFiltroDeltaDetalhes: () => operadorFiltroDeltaDetalhes,
   zColunaFiltroDelta: () => zColunaFiltroDelta,
   zCondicaoFiltroDelta: () => zCondicaoFiltroDelta,
   zFiltroDelta: () => zFiltroDelta,
@@ -35,7 +37,45 @@ __export(filtroDelta_exports, {
 });
 module.exports = __toCommonJS(filtroDelta_exports);
 var import_zod = __toESM(require("zod"));
-const zOperadorFiltroDelta = import_zod.default.enum([">", "<", ">=", "<=", "=", "!=", "in", "like"]);
+const zOperadorFiltroDelta = import_zod.default.enum([">", "<", ">=", "<=", "=", "!=", "in", "like", "\u2229"]);
+const operadorFiltroDeltaDetalhes = {
+  ">": {
+    rotulo: "Maior que",
+    descricao: "O valor de A deve ser maior que o valor de B"
+  },
+  "<": {
+    rotulo: "Menor que",
+    descricao: "O valor de A deve ser menor que o valor de B"
+  },
+  ">=": {
+    rotulo: "Maior ou igual a",
+    descricao: "O valor de A deve ser maior ou igual ao valor de B"
+  },
+  "<=": {
+    rotulo: "Menor ou igual a",
+    descricao: "O valor de A deve ser menor ou igual ao valor de B"
+  },
+  "=": {
+    rotulo: "Igual a",
+    descricao: "O valor de A deve ser igual ao valor de B"
+  },
+  "!=": {
+    rotulo: "Diferente de",
+    descricao: "O valor de A deve ser diferente do valor de B"
+  },
+  in: {
+    rotulo: "Est\xE1 em",
+    descricao: "O valor de A deve estar presente na cole\xE7\xE3o ou lista definida em B"
+  },
+  like: {
+    rotulo: "Cont\xE9m",
+    descricao: "O valor de A deve conter o texto informado em B"
+  },
+  "\u2229": {
+    rotulo: "Interse\xE7\xE3o",
+    descricao: "A e B devem possuir pelo menos um elemento em comum"
+  }
+};
 const regexIdCondicaoFiltroDelta = /^\{[\w:]+\}$/;
 const regexColunaFiltroDelta = /^\w+(\.\w+)*$/;
 const zColunaFiltroDelta = import_zod.default.string().regex(regexColunaFiltroDelta, "Coluna inv\xE1lida").describe("nome da coluna ou caminho aninhado do jsonb");
@@ -100,8 +140,15 @@ const zFiltroDelta = import_zod.default.object({
     }
   }
 });
+const iniciarFiltroDelta = () => {
+  return {
+    criarFiltroDelta: (filtro) => zFiltroDelta.parse(filtro)
+  };
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  iniciarFiltroDelta,
+  operadorFiltroDeltaDetalhes,
   zColunaFiltroDelta,
   zCondicaoFiltroDelta,
   zFiltroDelta,

dist-front/index.d.mts

@@ -129,6 +129,44 @@ declare const extensoes: {
  */
 declare const tipoArquivo: (nomeArquivo: string | null | undefined) => tiposArquivo;
 
+/**
+ * =============================================================================
+ * FILTRO DELTA (zFiltroDelta)
+ * =============================================================================
+ *
+ * OBJETIVO
+ * -----------------------------------------------------------------------------
+ * Novo sistema de filtros projetado para maior flexibilidade e geração segura
+ * de instruções SQL dinâmicas (WHERE).
+ *
+ * REGRAS IMPORTANTES (PARA IA)
+ * -----------------------------------------------------------------------------
+ * - O filtro é composto de duas partes obrigatórias: `condicoes` e `formula`.
+ * - Apenas referências aos `id`s das `condicoes` podem ser usadas na `formula`.
+ * - Não use sintaxe baseada em objetos aninhados para agrupamento (ex: { E: [], OU: [] }). Use fórmulas em string.
+ *
+ * 1) CONDIÇÕES (`condicoes`):
+ * Array de objetos contendo as definições isoladas de cada comparação.
+ * Exemplo:
+ * [
+ *   { id: "{1}", coluna: "idade", operador: ">=", valor: 18 },
+ *   { id: "{2}", coluna: "nome", operador: "like", valor: "%pa%" }
+ * ]
+ * - `id`: Deve SEMPRE seguir o formato {identificador}. Ex: `{c1}`, `{idade_min}`.
+ * - `coluna`: O nome da coluna ou um path JSONB válido (ex: `veiculo.ano`).
+ * - `operador`: Um dos valores do tipo `tipoOperadorFiltroDelta` (veja a constante).
+ *
+ * 2) FÓRMULA (`formula`):
+ * String que define a expressão lógica relacionando as condições através de seus `id`s.
+ * Operadores Lógicos Suportados (EM MAIÚSCULO):
+ * - `E` (AND)
+ * - `OU` (OR)
+ * - `NAO` (NOT)
+ * Suporta o agrupamento lógico usando parênteses `()`
+ * Exemplo válido: "({1} E NAO({2})) OU {3}"
+ *
+ * =============================================================================
+ */
 /**
  * Operadores permitidos para comparação.
  */
@@ -141,6 +179,11 @@ declare const zOperadorFiltroDelta: z.ZodEnum<{
     "<=": "<=";
     like: "like";
     in: "in";
+    "\u2229": "∩";
+}>;
+declare const operadorFiltroDeltaDetalhes: Record<z.infer<typeof zOperadorFiltroDelta>, {
+    rotulo: string;
+    descricao: string;
 }>;
 /**
  * Coluna simples ou caminho aninhado de jsonb.
@@ -161,6 +204,7 @@ declare const zCondicaoFiltroDelta: z.ZodObject<{
         "<=": "<=";
         like: "like";
         in: "in";
+        "\u2229": "∩";
     }>;
     valor: z.ZodAny;
 }, z.core.$strip>;
@@ -180,6 +224,7 @@ declare const zFiltroDelta: z.ZodObject<{
             "<=": "<=";
             like: "like";
             in: "in";
+            "\u2229": "∩";
         }>;
         valor: z.ZodAny;
     }, z.core.$strip>>;
@@ -189,6 +234,33 @@ type tipoOperadorFiltroDelta = z.infer<typeof zOperadorFiltroDelta>;
 type tipoColunaFiltroDelta = z.infer<typeof zColunaFiltroDelta>;
 type tipoCondicaoFiltroDelta = z.infer<typeof zCondicaoFiltroDelta>;
 type tipoFiltroDelta = z.infer<typeof zFiltroDelta>;
+type tipoFiltroDeltaColunaTipada<T extends string> = {
+    condicoes: (tipoCondicaoFiltroDelta & {
+        coluna: T;
+    })[];
+    formula: string;
+};
+/**
+ * Fábrica para criar filtros com colunas estritamente tipadas.
+ * Útil para autocompletar os nomes das colunas e garantir a estrutura no TypeScript.
+ *
+ * @example
+ * ```ts
+ * const { criarFiltroDelta } = iniciarFiltroDelta<"nome" | "idade" | "jsonb.propriedade">()
+ *
+ * const filtro = criarFiltroDelta({
+ *   condicoes: [
+ *     { id: "{c1}", coluna: "idade", operador: ">", valor: 18 },
+ *     { id: "{c2}", coluna: "nome", operador: "=", valor: "luiz" },
+ *     { id: "{c3}", coluna: "jsonb.propriedade", operador: "=", valor: "valor" },
+ *   ],
+ *   formula: "({c1} E {c2}) OU {c3}",
+ * })
+ * ```
+ */
+declare const iniciarFiltroDelta: <TColunas extends string>() => {
+    criarFiltroDelta: (filtro: tipoFiltroDeltaColunaTipada<TColunas>) => tipoFiltroDeltaColunaTipada<TColunas>;
+};
 
 /**
  * LocalStorage Tipado
@@ -402,4 +474,4 @@ declare const nomeVariavel: (v: {
     [key: string]: any;
 }) => string;
 
-export { Produtos, TipagemRotas, type TipoPayloadAuditoria, aleatorio, cacheM, cacheMFixo, cacheMemoria, camposComuns, erUuid, esperar, extensoes, type interfaceConsulta, link_paiol, localValor, nomeVariavel, objetoPg, operadores, paraObjetoRegistroPg, pgObjeto, siglas_unidades_medida, texto_busca, tipoArquivo, type tipoColunaFiltroDelta, type tipoCondicaoFiltroDelta, type tipoFiltro, type tipoFiltroDelta, type tipoOperadorFiltroDelta, tipoUsuarioResiduos, tiposSituacoesElicencie, tx, umaFuncao, umaVariavel, unidades_medida, uuid, uuidV3, uuidV4, uuid_null, validarUuid, verCacheM, zColunaFiltroDelta, zCondicaoFiltroDelta, zFiltro, zFiltroDelta, zOperadorFiltroDelta, zOperadores };
+export { Produtos, TipagemRotas, type TipoPayloadAuditoria, aleatorio, cacheM, cacheMFixo, cacheMemoria, camposComuns, erUuid, esperar, extensoes, iniciarFiltroDelta, type interfaceConsulta, link_paiol, localValor, nomeVariavel, objetoPg, operadorFiltroDeltaDetalhes, operadores, paraObjetoRegistroPg, pgObjeto, siglas_unidades_medida, texto_busca, tipoArquivo, type tipoColunaFiltroDelta, type tipoCondicaoFiltroDelta, type tipoFiltro, type tipoFiltroDelta, type tipoFiltroDeltaColunaTipada, type tipoOperadorFiltroDelta, tipoUsuarioResiduos, tiposSituacoesElicencie, tx, umaFuncao, umaVariavel, unidades_medida, uuid, uuidV3, uuidV4, uuid_null, validarUuid, verCacheM, zColunaFiltroDelta, zCondicaoFiltroDelta, zFiltro, zFiltroDelta, zOperadorFiltroDelta, zOperadores };

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "p-comuns",
-	"version": "0.339.0",
+	"version": "0.342.0",
 	"description": "",
 	"main": "./dist-front/index.mjs",
 	"module": "./dist-front/index.mjs",

src/filtroDelta.ts

@@ -1,9 +1,90 @@
 import z from "zod"
 
+/**
+ * =============================================================================
+ * FILTRO DELTA (zFiltroDelta)
+ * =============================================================================
+ *
+ * OBJETIVO
+ * -----------------------------------------------------------------------------
+ * Novo sistema de filtros projetado para maior flexibilidade e geração segura
+ * de instruções SQL dinâmicas (WHERE).
+ *
+ * REGRAS IMPORTANTES (PARA IA)
+ * -----------------------------------------------------------------------------
+ * - O filtro é composto de duas partes obrigatórias: `condicoes` e `formula`.
+ * - Apenas referências aos `id`s das `condicoes` podem ser usadas na `formula`.
+ * - Não use sintaxe baseada em objetos aninhados para agrupamento (ex: { E: [], OU: [] }). Use fórmulas em string.
+ *
+ * 1) CONDIÇÕES (`condicoes`):
+ * Array de objetos contendo as definições isoladas de cada comparação.
+ * Exemplo:
+ * [
+ *   { id: "{1}", coluna: "idade", operador: ">=", valor: 18 },
+ *   { id: "{2}", coluna: "nome", operador: "like", valor: "%pa%" }
+ * ]
+ * - `id`: Deve SEMPRE seguir o formato {identificador}. Ex: `{c1}`, `{idade_min}`.
+ * - `coluna`: O nome da coluna ou um path JSONB válido (ex: `veiculo.ano`).
+ * - `operador`: Um dos valores do tipo `tipoOperadorFiltroDelta` (veja a constante).
+ *
+ * 2) FÓRMULA (`formula`):
+ * String que define a expressão lógica relacionando as condições através de seus `id`s.
+ * Operadores Lógicos Suportados (EM MAIÚSCULO):
+ * - `E` (AND)
+ * - `OU` (OR)
+ * - `NAO` (NOT)
+ * Suporta o agrupamento lógico usando parênteses `()`
+ * Exemplo válido: "({1} E NAO({2})) OU {3}"
+ *
+ * =============================================================================
+ */
+
 /**
  * Operadores permitidos para comparação.
  */
-export const zOperadorFiltroDelta = z.enum([">", "<", ">=", "<=", "=", "!=", "in", "like"])
+export const zOperadorFiltroDelta = z.enum([">", "<", ">=", "<=", "=", "!=", "in", "like", "∩"])
+
+export const operadorFiltroDeltaDetalhes: Record<
+  z.infer<typeof zOperadorFiltroDelta>,
+  { rotulo: string; descricao: string }
+> = {
+  ">": {
+    rotulo: "Maior que",
+    descricao: "O valor de A deve ser maior que o valor de B",
+  },
+  "<": {
+    rotulo: "Menor que",
+    descricao: "O valor de A deve ser menor que o valor de B",
+  },
+  ">=": {
+    rotulo: "Maior ou igual a",
+    descricao: "O valor de A deve ser maior ou igual ao valor de B",
+  },
+  "<=": {
+    rotulo: "Menor ou igual a",
+    descricao: "O valor de A deve ser menor ou igual ao valor de B",
+  },
+  "=": {
+    rotulo: "Igual a",
+    descricao: "O valor de A deve ser igual ao valor de B",
+  },
+  "!=": {
+    rotulo: "Diferente de",
+    descricao: "O valor de A deve ser diferente do valor de B",
+  },
+  in: {
+    rotulo: "Está em",
+    descricao: "O valor de A deve estar presente na coleção ou lista definida em B",
+  },
+  like: {
+    rotulo: "Contém",
+    descricao: "O valor de A deve conter o texto informado em B",
+  },
+  "∩": {
+    rotulo: "Interseção",
+    descricao: "A e B devem possuir pelo menos um elemento em comum",
+  },
+}
 
 /**
  * Valida o identificador da condição.
@@ -160,3 +241,32 @@ export type tipoOperadorFiltroDelta = z.infer<typeof zOperadorFiltroDelta>
 export type tipoColunaFiltroDelta = z.infer<typeof zColunaFiltroDelta>
 export type tipoCondicaoFiltroDelta = z.infer<typeof zCondicaoFiltroDelta>
 export type tipoFiltroDelta = z.infer<typeof zFiltroDelta>
+
+export type tipoFiltroDeltaColunaTipada<T extends string> = {
+  condicoes: (tipoCondicaoFiltroDelta & { coluna: T })[]
+  formula: string
+}
+/**
+ * Fábrica para criar filtros com colunas estritamente tipadas.
+ * Útil para autocompletar os nomes das colunas e garantir a estrutura no TypeScript.
+ *
+ * @example
+ * ```ts
+ * const { criarFiltroDelta } = iniciarFiltroDelta<"nome" | "idade" | "jsonb.propriedade">()
+ *
+ * const filtro = criarFiltroDelta({
+ *   condicoes: [
+ *     { id: "{c1}", coluna: "idade", operador: ">", valor: 18 },
+ *     { id: "{c2}", coluna: "nome", operador: "=", valor: "luiz" },
+ *     { id: "{c3}", coluna: "jsonb.propriedade", operador: "=", valor: "valor" },
+ *   ],
+ *   formula: "({c1} E {c2}) OU {c3}",
+ * })
+ * ```
+ */
+export const iniciarFiltroDelta = <TColunas extends string>() => {
+  return {
+    criarFiltroDelta: (filtro: tipoFiltroDeltaColunaTipada<TColunas>) =>
+      zFiltroDelta.parse(filtro) as tipoFiltroDeltaColunaTipada<TColunas>,
+  }
+}