npm package: @mkgalaxy/ultimate-utils
Description: A versatile npm package with TypeScript utilities, React components, and Parse Server integration. Works seamlessly with Next.js, React, and Node.js.
Author: Your Name
Latest version: 1.0.12

# Ultimate Utils

A versatile npm package with TypeScript utilities, React components, and Parse Server integration. Works seamlessly with React, Next.js, and vanilla JavaScript/TypeScript projects.

## Features

- 🚀 **TypeScript First**: Fully typed for better DX
- ⚛️ **React Components**: Ready-to-use components with Parse Server integration
- 🔧 **Utility Functions**: Common utilities for everyday tasks
- 🗄️ **Parse Server Integration**: Built-in Parse Server operations and hooks
- 📦 **Multiple Entry Points**: Import only what you need
- 🎯 **Next.js Compatible**: Works as client components in Next.js 13+

## Installation

```bash
npm install @your-org/ultimate-utils
# or
yarn add @your-org/ultimate-utils
# or
pnpm add @your-org/ultimate-utils
```

## Usage

### 1. Using Utility Functions (No React Required)

```typescript
import { formatDate, debounce, isValidEmail } from '@your-org/ultimate-utils/utils';

// Format dates
const formatted = formatDate(new Date());

// Debounce functions
const debouncedSearch = debounce((query: string) => {
  console.log('Searching:', query);
}, 300);

// Validate email
const valid = isValidEmail('user@example.com');
```

### 2. Parse Server Setup (Node.js/React/Next.js)

#### Initialize Parse Server

```typescript
// In your app initialization (e.g., _app.tsx for Next.js or App.tsx for React)
import { initializeParse } from '@your-org/ultimate-utils';

initializeParse({
  serverURL: 'https://your-parse-server.com/parse',
  appId: 'your-app-id',
  javascriptKey: 'your-javascript-key',
});
```

#### Using Parse Provider in React/Next.js

```tsx
// app/layout.tsx (Next.js 13+) or App.tsx (React)
'use client';

import { ParseProvider } from '@your-org/ultimate-utils/react';

export default function RootLayout({ children }) {
  const parseConfig = {
    serverURL: process.env.NEXT_PUBLIC_PARSE_SERVER_URL!,
    appId: process.env.NEXT_PUBLIC_PARSE_APP_ID!,
    javascriptKey: process.env.NEXT_PUBLIC_PARSE_JS_KEY,
  };

  return (
    <html lang="en">
      <body>
        <ParseProvider config={parseConfig}>{children}</ParseProvider>
      </body>
    </html>
  );
}
```

### 3. Using React Components

#### Next.js 13+ (App Router)

```tsx
'use client';

import { Button, Input, ParseDataFetcher } from '@your-org/ultimate-utils/react';

export default function MyPage() {
  return (
    <div>
      <Button variant="primary" onClick={() => alert('Clicked!')}>
        Click Me
      </Button>

      <Input label="Email" type="email" placeholder="Enter your email" />

      <ParseDataFetcher
        className="Post"
        options={{ limit: 10, descending: 'createdAt' }}
        renderData={(posts) => (
          <div>
            {posts.map((post) => (
              <div key={post.id}>
                <h3>{post.get('title')}</h3>
                <p>{post.get('content')}</p>
              </div>
            ))}
          </div>
        )}
      />
    </div>
  );
}
```

#### React (Create React App or Vite)

```tsx
import { Button, Input } from '@your-org/ultimate-utils/react';

function App() {
  return (
    <div>
      <Button variant="secondary" size="large">
        My Button
      </Button>

      <Input label="Username" helperText="Enter your username" />
    </div>
  );
}
```

### 4. Using Parse Server Hooks

```tsx
'use client';

import { useParseQuery, useParseMutation } from '@your-org/ultimate-utils/react';

function MyComponent() {
  // Fetch data
  const { data, loading, error, refetch } = useParseQuery('Post', {
    limit: 10,
    descending: 'createdAt',
  });

  // Mutate data
  const { mutate, remove } = useParseMutation('Post');

  const handleCreate = async () => {
    await mutate({ title: 'New Post', content: 'Content here' });
    refetch();
  };

  const handleDelete = async (id: string) => {
    await remove(id);
    refetch();
  };

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <button onClick={handleCreate}>Create Post</button>
      {data.map((post) => (
        <div key={post.id}>
          <h3>{post.get('title')}</h3>
          <button onClick={() => handleDelete(post.id)}>Delete</button>
        </div>
      ))}
    </div>
  );
}
```

### 5. Direct Parse Operations

```typescript
import {
  fetchParseData,
  saveParseObject,
  deleteParseObject,
  getParseObjectById,
} from '@your-org/ultimate-utils';

// Fetch data
const posts = await fetchParseData('Post', {
  limit: 20,
  descending: 'createdAt',
});

// Create or update
const newPost = await saveParseObject('Post', {
  title: 'My Post',
  content: 'Post content',
});

// Get by ID
const post = await getParseObjectById('Post', 'postId123');

// Delete
await deleteParseObject('Post', 'postId123');
```

## API Reference

### Utilities

- `formatDate(date, locale?)` - Format dates
- `debounce(func, wait)` - Debounce function calls
- `deepClone(obj)` - Deep clone objects
- `generateId()` - Generate unique IDs
- `isValidEmail(email)` - Validate email format
- `truncateText(text, maxLength)` - Truncate text with ellipsis
- `sleep(ms)` - Async sleep/wait
- `groupBy(array, key)` - Group array by key

### Parse Functions

- `initializeParse(config)` - Initialize Parse Server
- `fetchParseData(className, options?)` - Fetch data from Parse
- `saveParseObject(className, data, objectId?)` - Create/update object
- `deleteParseObject(className, objectId)` - Delete object
- `getParseObjectById(className, objectId, include?)` - Get single object

### React Hooks

- `useParseQuery(className, options?)` - Fetch Parse data with React
- `useParseMutation(className)` - Mutate Parse data
- `useParse()` - Access Parse context

### React Components

- `ParseProvider` - Initialize Parse for React app
- `ParseDataFetcher` - Generic data fetching component
- `Button` - Reusable button component
- `Input` - Reusable input component

## Environment Variables

For Next.js projects, create a `.env.local` file:

```env
NEXT_PUBLIC_PARSE_SERVER_URL=https://your-parse-server.com/parse
NEXT_PUBLIC_PARSE_APP_ID=your-app-id
NEXT_PUBLIC_PARSE_JS_KEY=your-javascript-key
```

## TypeScript Support

This package is written in TypeScript and includes type definitions. No need for `@types` packages.

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.