@archbase/data 3.0.0

package/dist/datasource/IArchbaseDataSourceBase.d.ts

@@ -0,0 +1,111 @@
+import { DataSourceListener } from './ArchbaseDataSource';
+/**
+ * Interface base para DataSources usados em componentes de binding.
+ *
+ * Esta interface define o contrato mínimo que TODOS os DataSources devem implementar
+ * para serem compatíveis com componentes como ArchbaseEdit, ArchbaseSelect, etc.
+ *
+ * Tanto ArchbaseDataSource quanto ArchbaseRemoteDataSourceV2 implementam esta interface.
+ *
+ * @example
+ * ```typescript
+ * // Em componentes, use esta interface ao invés de classes concretas:
+ * interface MyComponentProps<T> {
+ *   dataSource?: IArchbaseDataSourceBase<T>;
+ *   dataField?: string;
+ * }
+ * ```
+ */
+export interface IArchbaseDataSourceBase<T> {
+    /**
+     * Retorna o nome do DataSource
+     */
+    getName(): string;
+    /**
+     * Verifica se o DataSource está ativo
+     */
+    isActive(): boolean;
+    /**
+     * Verifica se o DataSource está vazio (sem registros)
+     */
+    isEmpty(): boolean;
+    /**
+     * Verifica se o DataSource está em modo de navegação (browse)
+     */
+    isBrowsing(): boolean;
+    /**
+     * Verifica se o DataSource está em modo de edição
+     */
+    isEditing(): boolean;
+    /**
+     * Verifica se o DataSource está em modo de inserção
+     */
+    isInserting(): boolean;
+    /**
+     * Retorna o registro atual ou undefined se não houver registro
+     */
+    getCurrentRecord(): T | undefined;
+    /**
+     * Retorna o índice do registro atual
+     */
+    getCurrentIndex(): number;
+    /**
+     * Retorna o número total de registros na coleção filtrada
+     */
+    getTotalRecords(): number;
+    /**
+     * Retorna o número total de registros no servidor (para paginação)
+     */
+    getGrandTotalRecords(): number;
+    /**
+     * Retorna todos os registros da coleção filtrada
+     */
+    browseRecords(): T[];
+    /**
+     * Localiza um registro por valores de campos
+     * @param values Objeto com campos/valores para busca
+     * @returns true se encontrou, false caso contrário
+     */
+    locate(values: any): boolean;
+    /**
+     * Vai para um registro pelo seu índice
+     * @param index Índice do registro
+     */
+    gotoRecord(index: number): void;
+    /**
+     * Vai para um registro pelo seu dado
+     * @param record Dados do registro para navegar
+     * @returns true se encontrou, false caso contrário
+     */
+    gotoRecordByData(record: T): boolean;
+    /**
+     * Retorna a página atual (0-indexed)
+     */
+    getCurrentPage(): number;
+    /**
+     * Retorna o tamanho da página
+     */
+    getPageSize(): number;
+    /**
+     * Obtém o valor de um campo do registro atual
+     * @param fieldName Nome do campo (suporta notação de ponto para campos aninhados)
+     * @param defaultValue Valor padrão caso o campo seja undefined
+     */
+    getFieldValue(fieldName: string, defaultValue?: any): any;
+    /**
+     * Define o valor de um campo no registro atual
+     * @param fieldName Nome do campo (suporta notação de ponto para campos aninhados)
+     * @param value Novo valor do campo
+     */
+    setFieldValue(fieldName: string, value: any): void;
+    /**
+     * Adiciona um listener para eventos do DataSource
+     * @param listener Função que será chamada quando eventos ocorrerem
+     */
+    addListener(listener: DataSourceListener<T>): void;
+    /**
+     * Remove um listener de eventos do DataSource
+     * @param listener Função a ser removida
+     */
+    removeListener(listener: DataSourceListener<T>): void;
+}

package/dist/datasource/index.d.ts

@@ -0,0 +1,10 @@
+export type { DataSourceEvent, DataSourceEvents, DataSourceListener, DataSourceOptions, FilterFn, IDataSource, DataSourceEventRefreshDataType } from './ArchbaseDataSource';
+export type { IArchbaseDataSourceBase } from './IArchbaseDataSourceBase';
+export type { IDataSourceValidator, DataSourceValidationError } from '@archbase/core';
+export { DataSourceEventNames, ArchbaseDataSource } from './ArchbaseDataSource';
+export { ArchbaseRemoteDataSource } from './ArchbaseRemoteDataSource';
+export type { IRemoteDataSource } from './ArchbaseRemoteDataSource';
+export { ArchbaseLocalFilterDataSource, LocalFilter } from './ArchbaseLocalFilterDataSource';
+export { ArchbaseRemoteFilterDataSource, RemoteFilter } from './ArchbaseRemoteFilterDataSource';
+export * from './ArchbaseV1V2CompatibilityPattern';
+export * from './v2';

package/dist/datasource/v2/ArchbaseDataSourceV2.d.ts

@@ -0,0 +1,128 @@
+import { Draft } from 'immer';
+import { DataSourceListener, IDataSourceValidator, IDataSource, DataSourceOptions, FilterFn } from '../ArchbaseDataSource';
+/**
+ * Estados possíveis do DataSource
+ */
+type DataSourceState = 'browse' | 'edit' | 'insert';
+/**
+ * Configuração para ArchbaseDataSourceV2
+ */
+export interface ArchbaseDataSourceV2Config<T> {
+    name: string;
+    label?: string;
+    records?: T[];
+    validator?: IDataSourceValidator;
+    onStateChange?: (prevRecords: T[], newRecords: T[]) => void;
+    onFieldError?: (fieldName: string, error: string) => void;
+    onError?: (error: string, originalError?: any) => void;
+}
+/**
+ * ArchbaseDataSourceV2 - Versão V2 com Immer
+ *
+ * Esta implementação:
+ * - Garante imutabilidade completa com Immer
+ * - Interface simplificada focada em funcionalidade V2
+ * - Suporte a operações em arrays com type safety
+ * - Event system compatível com V1
+ */
+export declare class ArchbaseDataSourceV2<T> implements IDataSource<T> {
+    private name;
+    private label;
+    private records;
+    private currentIndex;
+    private state;
+    private listeners;
+    private originalRecord;
+    private validator?;
+    private lastDataChangedAt;
+    private active;
+    private onStateChange?;
+    private onFieldError?;
+    private onError?;
+    constructor(config: ArchbaseDataSourceV2Config<T>);
+    getName(): string;
+    getLabel(): string;
+    isActive(): boolean;
+    close(): void;
+    getCurrentRecord(): T | undefined;
+    getCurrentIndex(): number;
+    getTotalRecords(): number;
+    isEmpty(): boolean;
+    first(): this;
+    last(): this;
+    next(): this;
+    prior(): this;
+    goToRecord(index: number): T | undefined;
+    isFirst(): boolean;
+    isLast(): boolean;
+    isBOF(): boolean;
+    isEOF(): boolean;
+    isBrowsing(): boolean;
+    isEditing(): boolean;
+    isInserting(): boolean;
+    edit(): this;
+    cancel(): this;
+    insert(record: T): this;
+    save(callback?: Function): Promise<T>;
+    remove(callback?: Function): Promise<T | undefined>;
+    setFieldValue(fieldName: string, value: any): this;
+    getFieldValue(fieldName: string): any;
+    appendToFieldArray<K extends keyof T>(fieldName: K, item: T[K] extends Array<infer U> ? U : never): void;
+    updateFieldArrayItem<K extends keyof T>(fieldName: K, index: number, updater: (draft: T[K] extends Array<infer U> ? Draft<U> : never) => void): void;
+    removeFromFieldArray<K extends keyof T>(fieldName: K, index: number): void;
+    insertIntoFieldArray<K extends keyof T>(fieldName: K, index: number, item: T[K] extends Array<infer U> ? U : never): void;
+    getFieldArray<K extends keyof T>(fieldName: K): T[K] extends Array<infer U> ? U[] : never;
+    isFieldArray<K extends keyof T>(fieldName: K): boolean;
+    /**
+     * Abre o DataSource com os dados fornecidos.
+     * Aceita tanto o formato completo DataSourceOptions quanto um formato simplificado { records: T[] }
+     */
+    open(options: DataSourceOptions<T> | {
+        records: T[];
+    }): void;
+    clear(): void;
+    /**
+     * Define os dados do DataSource.
+     * Quando apenas records é informado, os valores de paginação são derivados automaticamente.
+     */
+    setData(options: DataSourceOptions<T> | {
+        records: T[];
+    }): void;
+    getOptions(): DataSourceOptions<T>;
+    refreshData(options?: DataSourceOptions<T>): void;
+    browseRecords(): T[];
+    getGrandTotalRecords(): number;
+    getCurrentPage(): number;
+    getTotalPages(): number;
+    isEmptyField(fieldName: string): boolean;
+    goToPage(pageNumber: number): this;
+    gotoRecordByData(record: T): boolean;
+    disabledAllListeners(): this;
+    enableAllListeners(): this;
+    addFieldChangeListener(fieldName: string, listener: (fieldName: string, oldValue: any, newValue: any) => void): this;
+    removeFieldChangeListener(fieldName: string, listener: (fieldName: string, oldValue: any, newValue: any) => void): this;
+    addFilter(filterFn: FilterFn<T>): this;
+    removeFilter(filterFn: FilterFn<T>): this;
+    clearFilters(): this;
+    locate(values: any): boolean;
+    locateByFilter(filterFn: (record: T) => boolean): boolean;
+    validate(): boolean;
+    addListener(...listeners: DataSourceListener<T>[]): this;
+    removeListener(...listeners: DataSourceListener<T>[]): this;
+    private emit;
+    getRecords(): T[];
+    setRecords(records: T[]): void;
+    getDebugSnapshot(): {
+        name: string;
+        recordCount: number;
+        currentIndex: number;
+        currentRecord: T;
+        state: DataSourceState;
+        listeners: number;
+    };
+    private validateDataSourceActive;
+    private notifyStateChange;
+    private setNestedValue;
+    private getNestedValue;
+}
+export {};

package/dist/datasource/v2/ArchbaseQueryIntegration.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Preparação para integração com TanStack Query
+ *
+ * Este arquivo define as estruturas e tipos necessários para integrar
+ * o ArchbaseDataSourceV2 com TanStack Query para gerenciamento avançado
+ * de cache e sincronização de dados remotos.
+ */
+import { ArchbaseRemoteDataSourceV2Config } from './ArchbaseRemoteDataSourceV2';
+import { ArchbaseRemoteApiService } from '../../service/ArchbaseRemoteApiService';
+/**
+ * Configuração para integração com TanStack Query
+ */
+export interface ArchbaseTanStackQueryConfig<T> {
+    /** Chave única para o cache do TanStack Query */
+    queryKey: string | string[];
+    /** Configuração do DataSource */
+    dataSourceConfig: Omit<ArchbaseRemoteDataSourceV2Config<T>, 'service'>;
+    /** Serviço para operações remotas */
+    service: ArchbaseRemoteApiService<T, any>;
+    /** Tempo de cache em milissegundos (padrão: 5 minutos) */
+    staleTime?: number;
+    /** Tempo para considerar dados expirados em milissegundos (padrão: 30 minutos) */
+    cacheTime?: number;
+    /** Refetch automático quando a janela ganha foco */
+    refetchOnWindowFocus?: boolean;
+    /** Refetch automático em intervalos */
+    refetchInterval?: number;
+    /** Habilitar retry automático em caso de erro */
+    retry?: boolean | number;
+    /** Função para transformar dados antes do cache */
+    transformData?: (data: T[]) => T[];
+    /** Função para validar se os dados em cache são válidos */
+    isDataValid?: (data: T[]) => boolean;
+}
+/**
+ * Estrutura para operações de cache do TanStack Query
+ */
+export interface ArchbaseQueryOperations<T> {
+    /** Invalidar cache */
+    invalidateQueries: () => void;
+    /** Refetch dados */
+    refetch: () => Promise<void>;
+    /** Definir dados no cache manualmente */
+    setQueryData: (data: T[]) => void;
+    /** Obter dados do cache */
+    getQueryData: () => T[] | undefined;
+    /** Remover do cache */
+    removeQueries: () => void;
+    /** Pré-carregar dados */
+    prefetchQuery: () => Promise<void>;
+}
+/**
+ * Estado do TanStack Query para o DataSource
+ */
+export interface ArchbaseQueryState {
+    /** Está carregando dados */
+    isLoading: boolean;
+    /** Está fazendo refetch */
+    isFetching: boolean;
+    /** Dados estão expirados */
+    isStale: boolean;
+    /** Erro da última operação */
+    error: Error | null;
+    /** Timestamp da última atualização */
+    dataUpdatedAt: number;
+    /** Status da query */
+    status: 'idle' | 'loading' | 'error' | 'success';
+}
+/**
+ * Hook futuro: useArchbaseDataSourceWithQuery
+ *
+ * Este hook combinará ArchbaseDataSourceV2 com TanStack Query
+ * para gerenciamento avançado de cache e sincronização.
+ *
+ * Funcionalidades planejadas:
+ * 1. Cache automático de dados remotos
+ * 2. Invalidação inteligente de cache
+ * 3. Refetch automático em cenários específicos
+ * 4. Otimistic updates para operações CRUD
+ * 5. Background refetch quando dados ficam stale
+ * 6. Retry automático em caso de falhas de rede
+ * 7. Prefetch de dados relacionados
+ * 8. Sincronização entre múltiplas instâncias do mesmo DataSource
+ *
+ * Exemplo de uso futuro:
+ *
+ * ```typescript
+ * const {
+ *   dataSource,
+ *   currentRecord,
+ *   isLoading,
+ *   isFetching,
+ *   error,
+ *   operations
+ * } = useArchbaseDataSourceWithQuery({
+ *   queryKey: ['pessoas', { filter: activeFilter }],
+ *   dataSourceConfig: {
+ *     name: 'pessoas-datasource',
+ *     pageSize: 20
+ *   },
+ *   service: pessoaService,
+ *   staleTime: 5 * 60 * 1000, // 5 minutos
+ *   cacheTime: 30 * 60 * 1000, // 30 minutos
+ *   refetchOnWindowFocus: true
+ * });
+ *
+ * // Invalidar cache quando dados são modificados
+ * const handleSave = async () => {
+ *   await dataSource.save();
+ *   operations.invalidateQueries();
+ * };
+ *
+ * // Prefetch dados relacionados
+ * useEffect(() => {
+ *   if (currentRecord) {
+ *     operations.prefetchQuery(['pessoa-detalhes', currentRecord.id]);
+ *   }
+ * }, [currentRecord]);
+ * ```
+ */
+/**
+ * Utilitários para integração com TanStack Query
+ */
+export declare class ArchbaseQueryUtils {
+    /**
+     * Gera chave de query baseada no DataSource e filtros
+     */
+    static generateQueryKey<T>(dataSourceName: string, filter?: any, sort?: any, page?: number): string[];
+    /**
+     * Determina se os dados precisam ser refetch baseado em critérios
+     */
+    static shouldRefetch(lastFetch: number, staleTime: number, userInteraction?: boolean): boolean;
+    /**
+     * Merge optimistic updates com dados em cache
+     */
+    static mergeOptimisticUpdate<T>(cachedData: T[], optimisticUpdate: Partial<T>, identifier: keyof T): T[];
+}
+/**
+ * Configurações padrão para diferentes cenários
+ */
+export declare const ARCHBASE_QUERY_DEFAULTS: {
+    /** Configuração para dados que mudam raramente */
+    readonly STATIC_DATA: {
+        readonly staleTime: number;
+        readonly cacheTime: number;
+        readonly refetchOnWindowFocus: false;
+        readonly retry: 1;
+    };
+    /** Configuração para dados dinâmicos */
+    readonly DYNAMIC_DATA: {
+        readonly staleTime: number;
+        readonly cacheTime: number;
+        readonly refetchOnWindowFocus: true;
+        readonly retry: 3;
+    };
+    /** Configuração para dados em tempo real */
+    readonly REALTIME_DATA: {
+        readonly staleTime: number;
+        readonly cacheTime: number;
+        readonly refetchOnWindowFocus: true;
+        readonly refetchInterval: number;
+        readonly retry: 5;
+    };
+};
+/**
+ * Tipos para implementação futura
+ */
+export type ArchbaseQueryHookReturn<T> = {
+    dataSource: any;
+    queryState: ArchbaseQueryState;
+    operations: ArchbaseQueryOperations<T>;
+    currentRecord?: T;
+    currentIndex: number;
+    totalRecords: number;
+    isLoading: boolean;
+    error: string | null;
+};
+/**
+ * Comentários para implementação futura:
+ *
+ * 1. INTEGRAÇÃO COM TANSTACK QUERY:
+ *    - Instalar @tanstack/react-query como dependência
+ *    - Criar wrapper que combine DataSource com useQuery/useMutation
+ *    - Implementar cache inteligente baseado em chaves geradas automaticamente
+ *
+ * 2. OPTIMISTIC UPDATES:
+ *    - Implementar updates otimistas para operações CRUD
+ *    - Rollback automático em caso de erro
+ *    - Sincronização com estado do DataSource
+ *
+ * 3. INVALIDAÇÃO DE CACHE:
+ *    - Invalidação automática após mutations
+ *    - Invalidação baseada em relacionamentos de dados
+ *    - Invalidação inteligente para queries relacionadas
+ *
+ * 4. BACKGROUND SYNC:
+ *    - Sincronização em background quando dados ficam stale
+ *    - Notificações quando dados são atualizados
+ *    - Merge inteligente de mudanças remotas
+ *
+ * 5. PERFORMANCE:
+ *    - Lazy loading de dados relacionados
+ *    - Prefetch de próximas páginas
+ *    - Cache de queries frequentes
+ *
+ * 6. OFFLINE SUPPORT:
+ *    - Persistência local de dados críticos
+ *    - Queue de operações para quando voltar online
+ *    - Indicadores de status de conexão
+ */

package/dist/datasource/v2/ArchbaseQueryProvider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ArchbaseQueryProvider - TanStack Query Provider for Archbase React
+ *
+ * This provider sets up TanStack Query with optimized defaults for Archbase DataSources
+ */
+import React, { ReactNode } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+/**
+ * Configuration for ArchbaseQueryProvider
+ */
+export interface ArchbaseQueryProviderConfig {
+    /** Enable React Query DevTools (default: true in development) */
+    enableDevTools?: boolean;
+    /** Custom QueryClient instance */
+    queryClient?: QueryClient;
+    /** Default stale time for all queries (default: 30 seconds) */
+    defaultStaleTime?: number;
+    /** Default cache time for all queries (default: 5 minutes) */
+    defaultCacheTime?: number;
+    /** Default retry count (default: 3) */
+    defaultRetry?: number;
+    /** Enable background refetch on window focus (default: false) */
+    refetchOnWindowFocus?: boolean;
+    /** Enable background refetch on reconnect (default: true) */
+    refetchOnReconnect?: boolean;
+    /** Global error handler */
+    onError?: (error: unknown) => void;
+    /** Global success handler for mutations */
+    onMutationSuccess?: (data: unknown) => void;
+}
+/**
+ * Create optimized QueryClient for Archbase applications
+ */
+export declare function createArchbaseQueryClient(config?: ArchbaseQueryProviderConfig): QueryClient;
+/**
+ * ArchbaseQueryProvider Component
+ */
+export interface ArchbaseQueryProviderProps extends ArchbaseQueryProviderConfig {
+    children: ReactNode;
+}
+export declare function ArchbaseQueryProvider({ children, queryClient, enableDevTools, ...config }: ArchbaseQueryProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the QueryClient
+ */
+export declare function useArchbaseQueryClient(): QueryClient;
+/**
+ * Hook for global query states
+ */
+export declare function useArchbaseQueryStates(): {
+    stats: {
+        total: number;
+        loading: number;
+        error: number;
+        success: number;
+        stale: number;
+        fresh: number;
+    };
+    queries: import("@tanstack/react-query").Query<unknown, Error, unknown, readonly unknown[]>[];
+    invalidateAll: () => Promise<void>;
+    clearAll: () => void;
+    refetchAll: () => Promise<void>;
+    isOnline: boolean;
+};
+/**
+ * Higher-order component for providing QueryClient
+ */
+export declare function withArchbaseQuery<P extends object>(Component: React.ComponentType<P>, config?: ArchbaseQueryProviderConfig): {
+    (props: P): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * DevTools component for debugging query state
+ */
+export declare function ArchbaseQueryDebugger(): import("react/jsx-runtime").JSX.Element;
+/**
+ * Offline indicator component
+ */
+export declare function ArchbaseOfflineIndicator(): import("react/jsx-runtime").JSX.Element;
+export default ArchbaseQueryProvider;