@base4u/client

🚀 React/React Native клієнтська бібліотека для Base4U - сучасна база даних з real-time оновленнями.

✨ Особливості

• 🔄 Real-time оновлення через WebSocket (Socket.IO)
• ⚛️ React Hooks - простий та зручний API
• 📱 React Native підтримка
• 🎯 TypeScript-ready (скоро)
• 🔐 Безпечна аутентифікація через API ключі
• 📦 Легковісна - мінімальні залежності
• 🎨 Гнучка - працює з будь-якими колекціями

📦 Встановлення

npm install @base4u/client socket.io-client
# або
yarn add @base4u/client socket.io-client

🚀 Швидкий старт

1. Обгорніть додаток в Provider

import { Base4UProvider } from '@base4u/client';

function App() {
  return (
    <Base4UProvider
      apiKey="your_api_key_here"
      baseURL="https://base4u.pp.ua"
      autoConnect={true}
    >
      <YourApp />
    </Base4UProvider>
  );
}

2. Використовуйте Hooks в компонентах

Real-time підписка (рекомендовано)

import { useRealtime } from '@base4u/client';

function UsersList() {
  const { data, loading, add, update, remove } = useRealtime('users');

  const handleAddUser = async () => {
    await add({
      name: 'Тарас',
      email: '[email protected]'
    });
  };

  if (loading) return <div>Завантаження...</div>;

  return (
    <div>
      {data.map(user => (
        <div key={user._id}>
          {user.name} - {user.email}
          <button onClick={() => remove(user._id)}>Видалити</button>
        </div>
      ))}
      <button onClick={handleAddUser}>Додати користувача</button>
    </div>
  );
}

Без real-time

import { useCollection } from '@base4u/client';

function Posts() {
  const { data, loading, add, update, remove } = useCollection('posts');

  // Той самий API, але без автоматичних оновлень
}

Робота з одним документом

import { useDocument } from '@base4u/client';

function UserProfile({ userId }) {
  const { data, loading, update } = useDocument('users', userId);

  if (loading) return <div>Завантаження...</div>;

  return (
    <div>
      <h1>{data.name}</h1>
      <button onClick={() => update({ name: 'Нове ім\'я' })}>
        Оновити
      </button>
    </div>
  );
}

📚 API Reference

Hooks

useBase4U()

Отримати клієнт та статус підключення.

const { client, connected, error, connect, disconnect } = useBase4U();

useRealtime(collectionName, options)

CRUD операції з real-time оновленнями.

const { 
  data,        // Масив документів
  loading,     // Стан завантаження
  error,       // Помилки
  lastChange,  // Остання зміна
  add,         // Додати документ
  update,      // Оновити документ
  remove       // Видалити документ
} = useRealtime('users');

useCollection(collectionName, query)

CRUD операції без real-time.

const { data, loading, error, refetch, add, update, remove } = 
  useCollection('posts', { status: 'published' });

useDocument(collectionName, documentId)

Робота з одним документом.

const { data, loading, error, update, remove } = 
  useDocument('users', 'user_id_here');

Прямий доступ до клієнта

import { useBase4U } from '@base4u/client';

function MyComponent() {
  const { client } = useBase4U();
  
  const users = client.collection('users');
  
  // REST API
  await users.add({ name: 'John' });
  await users.get({ age__gt: 18 });
  await users.getById('doc_id');
  await users.update('doc_id', { name: 'Jane' });
  await users.delete('doc_id');
  
  // Real-time підписка
  const unsubscribe = users.onSnapshot((change) => {
    console.log('Зміна:', change);
  });
  
  // Окремі події
  users.onInsert((change) => console.log('Новий документ'));
  users.onUpdate((change) => console.log('Оновлення'));
  users.onDelete((change) => console.log('Видалення'));
}

🔍 Запити з фільтрами

// Прості фільтри
const { data } = useCollection('users', { 
  city: 'Луцьк',
  age: 25 
});

// Оператори порівняння
const { data } = useCollection('products', {
  price__gt: 100,      // price > 100
  price__lt: 1000,     // price < 1000
  stock__gte: 10,      // stock >= 10
  category__in: 'electronics,phones',  // in array
});

// Сортування та пагінація
const { data } = useCollection('posts', {
  sort: '-createdAt',  // Сортування за датою (спадання)
  limit: 10,
  page: 1
});

📱 React Native приклад

import React from 'react';
import { View, Text, FlatList, Button } from 'react-native';
import { Base4UProvider, useRealtime } from '@base4u/client';

function UsersList() {
  const { data, loading, add, remove } = useRealtime('users');

  if (loading) return <Text>Завантаження...</Text>;

  return (
    <FlatList
      data={data}
      keyExtractor={item => item._id}
      renderItem={({ item }) => (
        <View>
          <Text>{item.name}</Text>
          <Button 
            title="Видалити" 
            onPress={() => remove(item._id)} 
          />
        </View>
      )}
    />
  );
}

export default function App() {
  return (
    <Base4UProvider
      apiKey="your_api_key"
      baseURL="https://your-server.com"
    >
      <UsersList />
    </Base4UProvider>
  );
}

⚙️ Налаштування

Base4UProvider Props

<Base4UProvider
  apiKey="your_api_key"           // Обов'язково: API ключ проєкту
  baseURL="http://localhost:3001" // Обов'язково: URL сервера
  autoConnect={true}               // Автоматичне підключення (default: true)
>

🔐 Безпека

• Ніколи не публікуйте API ключі в коді
• Використовуйте змінні середовища:

<Base4UProvider
  apiKey={process.env.REACT_APP_BASE4U_API_KEY}
  baseURL={process.env.REACT_APP_BASE4U_URL}
>

🛠️ Розробка

# Клонувати репозиторій
git clone https://github.com/base4u/base4u-client.git

# Встановити залежності
npm install

# Запустити приклади
npm run examples

📖 Документація

Повна документація доступна на https://doc.base4u.pp.ua(незабаром)

🤝 Внесок

Вітаються pull requests! Для великих змін спочатку відкрийте issue.

🫰 Підтримати проєкт

🔗Посилання на банку https://send.monobank.ua/jar/6ctUFdCJhB

💳Номер картки банки 4874 1000 2094 7266

📝 Ліцензія

MIT © Taras

🔗 Посилання

• GitHub
• NPM
• Документація(незабаром)

💬 Підтримка

• 📧 Email: [email protected]
• 💬 GitHub Issues: Create an issue

Зроблено з ❤️ в Україні 🇺🇦