open-index/open-npm huggingface dataset:
npm package: @perceived/optimistic-state
Description: Micro library for optimistic state with rollbacks and race condition handling.
Latest version: 1.0.0

# optimistic-state

Micro library for optimistic state with rollbacks and race condition handling.

## What and why an optimistic state?

[Optimistic UI and Optimistic States](https://github.com/perceived-dev/optimistic-state#what-is-an-optimistic-state)

## Installation

```
npm install @perceived/optimistic-state
```

## Usage

```js
import optimisticState from '@perceived/optimistic-state';
```

```js
function routine(state) {
  // async routine which should return promise
  return syncCounterToServer(state);
}

let count;

const updateState = optimisticState({
  initialState: 0,
  routine,
  handleState: (state) => {
    count = state;
    // handle optimistic state
    document.querySelector('.current-count').innerHTML = state;
  },
  handleResult: (result) => {
    document.querySelector('.result').innerHTML = result;
  },
  handleError: (err) => {
    // handle error, may be display error as toast/notification message
    message.error(err);
  },
});

document.querySelector('#increment-btn').addEventListener('click', () => {
  updateState(count + 1);
});
```

## API

### Types

- TState : Type of the optimistic state
- TResult: Type of api result (defaults to any)
- TError: Type of error (defaults to any)

### Options

#### initialState : `TState`

The initialState of optimistic state, before any action is fired.

#### routine : `(state: TState, ...args[]) => Promise`

Async routine (mostly an api call which sync client state to server). This routine must return a promise.

#### handleState: `(state: TState) => void;`

A callback to handle the optimistic state, this is fired when a routine is called, and also on rollbacks with the state.

#### handleResult: `(result: TResult) => void;`

The handleResult is called when the last action is resolved with the resolved data. In case of error on last action it is called with the last resolved data of action where it is rolled back.

For example if if there is series of action X, Y, Z. If Z is resolved (irrespective of X, Y failed or passed), handleResult will be called with Z data. But in case if Y, Z fails, handleResult will be called with X data.

#### handleError: `(err: TError) => void;`

The handleError will be called with reject reason, if the last action in series of action fails.

Note: If last action is passed and there is failure on previous actions, it will not call handleError

### Return

#### updateState: `(state: TState, ...args[] ) => void`

optimisticState return a updater function, which accepts new state as first argument, followed by any number of arguments. All of the arguments are passed to routine function.

## Demo

Try simulating all the cases in this example. [https://codesandbox.io/s/optimistic-state-rc9m5](https://codesandbox.io/s/optimistic-state-rc9m5)
npm package: @perceived/use-optimistic-state
Description: React hooks for optimistic state with rollbacks and race condition handling.
Latest version: 1.0.0

# use-optimistic-state

React hooks for optimistic state with rollbacks and race condition handling.

## What and why an optimistic state?

[Optimistic UI and Optimistic States](https://github.com/perceived-dev/optimistic-state#what-is-an-optimistic-state)

## Installation

```
npm install @perceived/use-optimistic-state
```

## Usage

```js
import useOptimisticState from '@perceived/use-optimistic-state';
```

```js
function routine(state) {
  // async routine which should return promise
  return syncCounterToServer(state);
}

function App() {
  const { state, updateState, result, error, loading } = useOptimisticState(0, routine);

  return (
    <div>
      ...
      <span>Likes: ${state}</span>
      <button onClick={() => updateState(state + 1)}>Like</button>
      ...
    </div>
  );
}
```

## API

### Types

- TState : Type of the optimistic state
- TResult: Type of api result (defaults to any)
- TError: Type of error (defaults to any)

### Arguments

#### initialState : `TState`

The initialState of optimistic state, before any action is fired.

#### routine : `(state: TState, ...args[]) => Promise`

Async routine (mostly an api call which sync client state to server). This routine must return a promise.

### Return properties

#### state: `TState;`

This represents up to date optimistic states. Its updated before the routine start and on rollbacks.

#### result: `TResult`

This represent to the up to date last resolved data from series of actions. It is set when the last action is resolved. In case of error on last action, it is set with the last resolved data of action where it is rolled back.

For example if if there is series of action X, Y, Z. If Z is resolved (irrespective of X, Y failed or passed), handleResult will be called with Z data. But in case if Y, Z fails, handleResult will be called with X data.

#### error: `TError`

The error is set when the last action (in series of actions) fails. If last action is passed and there is failure on previous actions it will not set the error.

Note: It resets when ever we trigger the routine again.

#### loading: `boolean`

It represents the loading state while action is triggered, it resets back when the optimistic state is resolved from backend.

Note: If there is series of simultaneous actions, it will maintain the loading state until the final state is resolved/rejected.

## Demo

Try simulating all the cases in this example. [https://codesandbox.io/s/use-optimistic-state-g5hds](https://codesandbox.io/s/use-optimistic-state-g5hds)
npm package: @percepta/create-mosaic-module
Description: Scaffold a new Mosaic package
Latest version: 1.1.0

# @percepta/create-app

Create a new Percepta app from the Next.js template.

## Usage

```bash
# Interactive mode
npx @percepta/create-app

# With project directory
npx @percepta/create-app my-new-app

# With all options (non-interactive)
npx @percepta/create-app my-new-app --yes

# Skip optional steps
npx @percepta/create-app my-new-app --skip-install --skip-git

# Use different package manager
npx @percepta/create-app my-new-app --use-npm
npx @percepta/create-app my-new-app --use-yarn
```

## Options

| Option | Description |
|--------|-------------|
| `--name <name>` | Project name (defaults to directory name) |
| `--title <title>` | Display title (defaults to title case of name) |
| `--skip-install` | Skip dependency installation |
| `--skip-git` | Skip git initialization |
| `--use-npm` | Use npm instead of pnpm |
| `--use-yarn` | Use yarn instead of pnpm |
| `-y, --yes` | Skip all prompts and use defaults |

## What's Included

The template includes:

- **Next.js 15** with App Router and Pages Router
- **Authentication** via NextAuth.js (Google, Okta, Ping Identity, Credentials)
- **Database** with PostgreSQL and Drizzle ORM
- **Type-safe API** with tRPC
- **Background Jobs** with Inngest
- **Observability** with OpenTelemetry and Langfuse
- **Infrastructure as Code** with Terraform (AWS)
- **Styling** with Tailwind CSS

## Development

### Building the CLI

```bash
pnpm build
```

### Testing locally

```bash
# Build the CLI
pnpm build

# Link globally
npm link

# Test creating a project
create-percepta-app test-app
```

### Syncing template files

When the base template is updated, sync the changes:

```bash
pnpm sync-template
```

Then manually review and update the `.template` files if needed:
- `template/package.json.template`
- `template/gitignore.template`
- `template/env.example.template`

## Publishing

```bash
pnpm publish --access public
```