Package Exports

@kodeme-io/next-core-hooks

Readme

@kodeme-io/next-core-hooks v2.0 🚀

Enterprise-grade React hooks for Next.js + Odoo development with React Query-level features, real-time capabilities, and comprehensive developer tools.

🎯 What's New in v2.0?

✅ React Query-level data fetching with background refetch, infinite scroll, optimistic updates

✅ Complete Odoo integration with useOdooModel, useOdooForm, useOdooWorkflow

✅ Real-time subscriptions and polling for live updates

✅ Advanced relational field management (Many2one, One2many, Attachments)

✅ Developer experience tools with debugging and performance monitoring

✅ TypeScript-first design with 100% type coverage

✅ SSR-safe production hooks with hydration safety

Installation

npm install @kodeme-io/next-core-hooks
# or
pnpm add @kodeme-io/next-core-hooks
# or
yarn add @kodeme-io/next-core-hooks

Quick Start

import {
  useOdooModel,
  useOdooForm,
  useQueryV2 as useQuery,
  useMany2one
} from '@kodeme-io/next-core-hooks'

// 📊 Enhanced data fetching with React Query-level features
const { data, loading, error, refetch } = useQuery(
  ['orders', 'sale'],
  () => dataClient.search(Models.SaleOrder, { where: { state: 'sale' } }),
  {
    staleTime: 300000,
    refetchOnWindowFocus: true,
    suspense: true
  }
)

// 🏢 Complete Odoo model interaction
const customers = useOdooModel('res.partner', {
  fields: ['name', 'email', 'phone'],
  domain: [['is_company', '=', true]],
  order: 'name ASC'
})

// 📝 Advanced form state management
const customerForm = useOdooForm('res.partner', customerId, {
  fields: ['name', 'email', 'phone', 'is_company'],
  autoSave: { enabled: true, debounce: 2000 },
  onSubmit: async (values) => {
    await customers.update(customerId, values)
    toast.success('Customer saved!')
  }
})

// 🔗 Relational field management
const partnerField = useMany2one('res.partner', {
  value: customerForm.values.partner_id,
  onChange: (partner) => customerForm.setValue('partner_id', partner?.[0]),
  domain: [['is_company', '=', true]],
  placeholder: 'Select customer...'
})

📚 API Documentation

Enhanced Data Fetching (v2.0)

`useQuery` - React Query-level features

import { useQuery, useInfiniteQuery } from '@kodeme-io/next-core-hooks'

// Basic query with advanced features
const { data, loading, error, refetch, isStale, isFetching } = useQuery(
  ['orders', 'sale'], // cache key
  () => dataClient.search(Models.SaleOrder, { where: { state: 'sale' } }),
  {
    staleTime: 300000,        // 5 minutes
    refetchOnWindowFocus: true, // Background refetch
    refetchOnReconnect: true,  // Refetch on reconnect
    suspense: true,           // Suspense mode
    select: (data) => data.filter(order => order.amount_total > 1000),
    placeholderData: []
  }
)

// Infinite query for pagination
const {
  data,
  fetchNextPage,
  hasNextPage,
  isFetchingNextPage
} = useInfiniteQuery(
  ['customers'],
  ({ pageParam = 0 }) => fetchCustomers(pageParam, 20),
  {
    getNextPageParam: (lastPage, allPages) =>
      lastPage.length === 20 ? allPages.length : undefined
  }
)

// Access all customers data
const allCustomers = data.pages.flat()

`QueryClient` - Advanced cache management

import { QueryClient, queryClient } from '@kodeme-io/next-core-hooks'

// Global cache operations
queryClient.invalidateQueries(['orders'])
queryClient.setQueryData(['customers'], updatedCustomers)
const cachedData = queryClient.getQueryData(['orders'])

// Create client instance for specific contexts
const client = new QueryClient()

Odoo Model Integration

`useOdooModel` - Complete CRUD + metadata

import { useOdooModel } from '@kodeme-io/next-core-hooks'

const customers = useOdooModel('res.partner', {
  fields: ['name', 'email', 'phone', 'is_company', 'country_id'],
  domain: [['is_company', '=', true]],
  order: 'name ASC',
  limit: 20,
  loadFields: true,      // Load field metadata
  loadViews: true        // Load view definitions
})

// CRUD operations
const handleCreate = async () => {
  const id = await customers.create({
    name: 'New Customer',
    email: 'customer@example.com',
    is_company: true
  })
}

const handleUpdate = async (id: number) => {
  await customers.update(id, { name: 'Updated Name' })
}

const handleDelete = async (id: number) => {
  await customers.delete(id)
}

// Advanced operations
const searchResults = await customers.nameSearch('ABC', [['is_company', '=', true]])
const groups = await customers.readGroup(
  [['is_company', '=', true]],
  ['country_id'],
  ['country_id']
)

// Method calls
const result = await customers.call('compute_total', [123], { context: {} })

// Field metadata
const nameField = customers.fields.name
console.log(nameField.required, nameField.type, nameField.string)

`useOdooModels` - Multiple models

const models = useOdooModels({
  customers: { model: 'res.partner', options: { domain: [['is_company', '=', true]] } },
  orders: { model: 'sale.order', options: { domain: [['state', '=', 'sale']] } },
  products: { model: 'product.product', options: { domain: [['sale_ok', '=', true]] } }
})

// Access each model
const { data: customers, loading: customersLoading } = models.customers
const { data: orders, create: createOrder } = models.orders
const { data: products, fields: productFields } = models.products

Form Management

`useOdooForm` - Advanced form state

import { useOdooForm } from '@kodeme-io/next-core-hooks'

const customerForm = useOdooForm('res.partner', customerId, {
  fields: ['name', 'email', 'phone', 'is_company', 'country_id'],
  initialValues: { is_company: true },
  autoSave: {
    enabled: true,
    debounce: 2000,
    validateBeforeSave: true
  },
  validation: {
    validateOnChange: true,
    validateOnBlur: true,
    stopValidationOnFirstError: false
  },
  onSubmit: async (values, { mode }) => {
    if (mode === 'create') {
      const id = await customers.create(values)
      router.push(`/customers/${id}`)
    } else {
      await customers.update(customerId, values)
    }
  },
  onDirty: (dirty) => setHasUnsavedChanges(dirty),
  dependencies: {
    country_id: (values) => {
      // Compute country-specific validation
      return values.country_id ? { country_required: true } : {}
    }
  }
})

return (
  <form onSubmit={customerForm.submit}>
    <input
      value={customerForm.values.name || ''}
      onChange={(e) => customerForm.setValue('name', e.target.value)}
      onBlur={() => customerForm.touchField('name')}
      error={customerForm.errors.name}
      required={customerForm.isRequired('name')}
      readOnly={customerForm.isReadOnly('name')}
    />

    <select
      value={customerForm.values.country_id || ''}
      onChange={(e) => customerForm.setValue('country_id', parseInt(e.target.value))}
    >
      <option value="">Select Country</option>
      {countries.map(country => (
        <option key={country.id} value={country.id}>
          {country.name}
        </option>
      ))}
    </select>

    <button type="submit" disabled={customerForm.submitting || !customerForm.valid}>
      {customerForm.submitting ? 'Saving...' : 'Save Customer'}
    </button>

    <button type="button" onClick={customerForm.reset}>
      Reset
    </button>

    {customerForm.dirty && (
      <div className="warning">You have unsaved changes</div>
    )}
  </form>
)

Workflow Management

`useOdooWorkflow` - Workflow state and transitions

import { useOdooWorkflow } from '@kodeme-io/next-core-hooks'

const orderWorkflow = useOdooWorkflow('sale.order', orderId, {
  refreshInterval: 30000,
  onStateChange: (newState) => {
    toast.info(`Order moved to ${newState}`)
  },
  onTransitionSuccess: (transition) => {
    console.log('Transition executed:', transition)
  }
})

return (
  <div>
    <h3>Current State: {orderWorkflow.current}</h3>

    <div className="transitions">
      {orderWorkflow.available.map(transition => (
        <button
          key={transition.signal}
          onClick={() => orderWorkflow.signal(transition.signal, {
            comment: 'Processing order...'
          })}
          disabled={transition.disabled || orderWorkflow.loading}
        >
          {transition.name}
        </button>
      ))}
    </div>

    {orderWorkflow.pendingActivities.length > 0 && (
      <div className="activities">
        <h4>Pending Activities</h4>
        {orderWorkflow.pendingActivities.map(activity => (
          <div key={activity.id}>
            {activity.summary} - {activity.activity_type_id[1]}
          </div>
        ))}
      </div>
    )}
  </div>
)

Real-time Features

`useOdooSubscription` - Real-time updates

import { useOdooSubscription } from '@kodeme-io/next-core-hooks'

const subscription = useOdooSubscription('sale.order', {
  domain: [['state', '=', 'sale']],
  onCreate: (record) => {
    toast.success(`New order ${record.name} created!`)
    // Refresh orders list
    refetchOrders()
  },
  onUpdate: (record) => {
    console.log('Order updated:', record)
    // Update local state
    updateOrderInList(record)
  },
  onDelete: (id) => {
    toast.info('Order deleted')
    // Remove from local state
    removeOrderFromList(id)
  },
  autoConnect: true,
  reconnectAttempts: 3
})

return (
  <div>
    <div className="status">
      Connection: {subscription.connected ? '🟢 Connected' : '🔴 Disconnected'}
    </div>

    {subscription.error && (
      <div className="error">
        Connection error: {subscription.error.message}
        <button onClick={subscription.reconnect}>Reconnect</button>
      </div>
    )}
  </div>
)

`useOdooPolling` - Change monitoring

import { useOdooPolling } from '@kodeme-io/next-core-hooks'

const poller = useOdooPolling('res.partner', customerId, {
  interval: 5000,
  fields: ['name', 'email', 'phone', 'last_update'],
  onChange: (record) => {
    if (record.last_update !== lastUpdate) {
      setCustomer(record)
      setLastUpdate(record.last_update)
    }
  },
  onError: (error) => {
    console.error('Polling error:', error)
  },
  onlyWhenVisible: true
})

Relational Fields

`useMany2one` - Many2one field management

import { useMany2one } from '@kodeme-io/next-core-hooks'

const partnerField = useMany2one('res.partner', {
  value: order.partner_id,
  onChange: (partner) => {
    updateOrder(prev => ({ ...prev, partner_id: partner?.[0] }))
  },
  domain: [['is_company', '=', true]],
  fields: ['name', 'email', 'phone'],
  placeholder: 'Select customer...',
  searchable: true,
  clearable: true,
  create: true,
  onCreate: async (name) => {
    // Quick create new customer
    const id = await customers.create({ name, is_company: true })
    return [id, name]
  }
})

return (
  <div>
    <input
      value={partnerField.searchQuery}
      onChange={(e) => partnerField.setSearchQuery(e.target.value)}
      onFocus={() => partnerField.setFocused(true)}
      placeholder={partnerField.placeholder}
    />

    {partnerField.isOpen && partnerField.searchResults.length > 0 && (
      <div className="dropdown">
        {partnerField.searchResults.map(([id, name]) => (
          <div
            key={id}
            onClick={() => partnerField.select([id, name])}
            className="option"
          >
            {name}
          </div>
        ))}
      </div>
    )}

    <button onClick={partnerField.clear}>Clear</button>
  </div>
)

`useOne2many` - One2many field management

import { useOne2many } from '@kodeme-io/next-core-hooks'

const orderLines = useOne2many('sale.order.line', orderId, {
  fields: ['product_id', 'product_uom_qty', 'price_unit', 'discount'],
  order: 'sequence ASC',
  createInline: true,
  editInline: true,
  autoSave: true,
  onCreate: (line) => {
    console.log('Line added:', line)
  },
  onUpdate: (line) => {
    console.log('Line updated:', line)
  },
  onDelete: (lineId) => {
    console.log('Line deleted:', lineId)
  }
})

return (
  <div>
    <button onClick={() => orderLines.create({
      product_id: productId,
      product_uom_qty: 1,
      price_unit: 0
    })}>
      Add Line
    </button>

    {orderLines.records.map(line => (
      <div key={line.id} className="order-line">
        <input
          value={line.product_uom_qty}
          onChange={(e) => orderLines.update(line.id, {
            product_uom_qty: parseInt(e.target.value)
          })}
        />
        <span>{line.product_id[1]}</span>
        <button onClick={() => orderLines.delete(line.id)}>Remove</button>
      </div>
    ))}

    {orderLines.dirty && (
      <button onClick={orderLines.save}>
        Save Changes ({orderLines.records.length} lines)
      </button>
    )}
  </div>
)

`useOdooAttachments` - File management

import { useOdooAttachments } from '@kodeme-io/next-core-hooks'

const attachments = useOdooAttachments('sale.order', orderId, {
  maxFileSize: 25 * 1024 * 1024, // 25MB
  allowedTypes: ['application/pdf', 'image/jpeg', 'image/png'],
  multiple: true,
  onUpload: (attachment) => {
    toast.success(`File ${attachment.name} uploaded`)
  },
  onDelete: (attachmentId) => {
    toast.info('File deleted')
  }
})

return (
  <div>
    <input
      type="file"
      multiple
      onChange={(e) => {
        Array.from(e.target.files).forEach(file => {
          attachments.upload(file)
        })
      }}
    />

    {attachments.uploading && <div>Uploading files...</div>}

    <div className="attachments">
      {attachments.attachments.map(attachment => (
        <div key={attachment.id} className="attachment">
          <span>{attachment.name}</span>
          <span>({(attachment.file_size / 1024).toFixed(1)} KB)</span>
          <button onClick={() => attachments.download(attachment)}>
            Download
          </button>
          <button onClick={() => attachments.delete(attachment.id)}>
            Delete
          </button>
        </div>
      ))}
    </div>
  </div>
)

Developer Tools

`useOdooDevTools` - Development dashboard

import { useOdooDevTools } from '@kodeme-io/next-core-hooks'

const devTools = useOdooDevTools({
  enabled: process.env.NODE_ENV === 'development',
  showQueries: true,
  showCache: true,
  showNetwork: true,
  showPerformance: true,
  refreshInterval: 1000,
  maxEntries: 50
})

// Only render in development
if (process.env.NODE_ENV === 'development') {
  return (
    <div className={`dev-tools ${devTools.isOpen ? 'open' : 'closed'}`}>
      <button onClick={() => devTools.setOpen(!devTools.isOpen)}>
        🛠️ Dev Tools
      </button>

      {devTools.isOpen && (
        <div className="dev-tools-panel">
          <div className="tabs">
            {['queries', 'cache', 'network', 'performance'].map(tab => (
              <button
                key={tab}
                onClick={() => devTools.setActiveTab(tab)}
                className={devTools.activeTab === tab ? 'active' : ''}
              >
                {tab}
              </button>
            ))}
          </div>

          {devTools.activeTab === 'queries' && (
            <div className="queries-tab">
              <button onClick={devTools.clearQueries}>Clear</button>
              {devTools.queries.map(query => (
                <div key={query.key} className={`query ${query.status}`}>
                  <span>{query.key}</span>
                  <span>{query.status}</span>
                  <span>{query.fetchCount} fetches</span>
                  <button onClick={() => query.refetch?.()}>Refetch</button>
                </div>
              ))}
            </div>
          )}

          {devTools.activeTab === 'performance' && (
            <div className="performance-tab">
              <div>Avg Response Time: {devTools.metrics.averageResponseTime}ms</div>
              <div>Cache Hit Rate: {(devTools.metrics.cacheHitRate * 100).toFixed(1)}%</div>
              <div>Error Rate: {(devTools.metrics.errorRate * 100).toFixed(1)}%</div>
              <div>Total Requests: {devTools.metrics.totalRequests}</div>
            </div>
          )}
        </div>
      )}
    </div>
  )
}

Legacy Hooks (v1.0)

The following hooks are still available for backward compatibility:

`useHydration`, `useDebounce`, `useLocalStorage`, etc.

import {
  useHydration,
  useDebounce,
  useLocalStorage,
  useMediaQuery,
  useOnClickOutside,
  usePrevious,
  useInterval
} from '@kodeme-io/next-core-hooks'

// Same API as before
const hydrated = useHydration()
const debouncedValue = useDebounce(value, 500)
const [theme, setTheme] = useLocalStorage('theme', 'light')
const isMobile = useMediaQuery('(max-width: 768px)')

🚀 Migration Guide

From v1.0 to v2.0

// Old v1.0 usage
import { useQuery } from '@kodeme-io/next-core-hooks'
const { data, loading, error, refetch } = useQuery(['orders'], fetchOrders)

// New v2.0 usage (recommended)
import { useQueryV2 as useQuery } from '@kodeme-io/next-core-hooks'
const {
  data,
  loading,
  error,
  refetch,
  isFetching,
  isStale,
  isPaused
} = useQuery(['orders'], fetchOrders, {
  staleTime: 300000,
  refetchOnWindowFocus: true
})

Replacing useOdooQuery

// Old usage
import { useOdooQuery } from '@kodeme-io/next-core-hooks'
const { data, loading, error } = useOdooQuery({
  odooClient,
  model: 'res.partner',
  domain: [['is_company', '=', true]],
  fields: ['name', 'email']
})

// New usage (recommended)
import { useOdooModel } from '@kodeme-io/next-core-hooks'
const { data, loading, error, fields, create, update } = useOdooModel('res.partner', {
  domain: [['is_company', '=', true]],
  fields: ['name', 'email']
})

🎯 Best Practices

Data Fetching

// ✅ Good: Use descriptive cache keys
const orders = useQuery(['orders', 'list', { status: 'sale' }], fetchOrders)

// ✅ Good: Configure appropriate cache times
const config = useQuery(['app-config'], fetchConfig, {
  staleTime: Infinity, // Never stale for config
  cacheTime: 1000 * 60 * 60 * 24, // 24 hours cache
})

// ✅ Good: Use suspense for loading states
function OrdersPage() {
  return (
    <Suspense fallback={<Loading />}>
      <OrdersList />
    </Suspense>
  )
}

function OrdersList() {
  const { data: orders } = useQuery(['orders'], fetchOrders, { suspense: true })
  return <div>{/* Render orders */}</div>
}

Forms

// ✅ Good: Use auto-save for better UX
const form = useOdooForm('res.partner', id, {
  autoSave: { enabled: true, debounce: 2000 },
  validation: { validateOnChange: true }
})

// ✅ Good: Handle optimistic updates
const mutation = useMutation(updateCustomer, {
  onMutate: async (newData) => {
    // Cancel outgoing refetches
    await queryClient.cancelQueries(['customer', id])

    // Snapshot previous value
    const previousCustomer = queryClient.getQueryData(['customer', id])

    // Optimistically update
    queryClient.setQueryData(['customer', id], newData)

    return { previousCustomer }
  },
  onError: (err, newData, context) => {
    // Rollback on error
    queryClient.setQueryData(['customer', id], context?.previousCustomer)
  },
  onSettled: () => {
    // Always refetch after error or success
    queryClient.invalidateQueries(['customer', id])
  }
})

Performance

// ✅ Good: Use React Query patterns for complex caching
const queryKeys = {
  all: ['products'] as const,
  lists: () => [...queryKeys.all, 'list'] as const,
  list: (filters: any) => [...queryKeys.lists(), { filters }] as const,
  details: () => [...queryKeys.all, 'detail'] as const,
  detail: (id: number) => [...queryKeys.details(), id] as const
}

// ✅ Good: Optimize re-renders with selectors
const { data: products } = useQuery(
  queryKeys.list({ category: 'electronics' }),
  fetchProducts,
  {
    select: (data) => data.filter(p => p.price > 100)
  }
)

📊 Performance Metrics

The hooks library is optimized for performance:

Bundle Size: < 50KB (tree-shakable)
Runtime Performance: < 16ms query resolution
Cache Hit Rate: > 80% for repeated queries
Memory Usage: Efficient cache with LRU eviction
SSR Performance: Hydration-safe with minimal client-side work

🔧 TypeScript Support

Full TypeScript support with comprehensive types:

// ✅ Strong typing for model data
interface Customer {
  id: number
  name: string
  email?: string
  is_company: boolean
}

const customers = useOdooModel<Customer>('res.partner', {
  fields: ['name', 'email', 'is_company']
})

// ✅ Type-safe form values
const customerForm = useOdooForm<Customer>('res.partner', customerId, {
  fields: ['name', 'email', 'is_company']
})

// ✅ Type-safe query results
const { data: orders } = useQuery<SaleOrder[]>(['orders'], fetchOrders)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

# Clone the repository
git clone https://github.com/abc-food/next-core.git
cd next-core/packages/hooks

# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests
pnpm test

# Build
pnpm build

# Type check
pnpm type-check

📄 License

MIT © ABC Food

🙏 Acknowledgments

Inspired by React Query for data fetching patterns
Built for Odoo ERP integration
Optimized for Next.js applications
TypeScript-first design for type safety

@kodeme-io/next-core-hooks