npm package: @qt-test/apex-runtime
Description: Mini-app runtime framework for APEX platform
Author: Interswitch
Latest version: 0.1.0

# @interswitch/apex-runtime

> Mini-app runtime framework for APEX platform

This package provides the core runtime framework for APEX mini-apps, including app lifecycle management, page routing, component system, and reactivity.

## Installation

```bash
npm install @interswitch/apex-runtime
```

## Usage

### App Definition

```javascript
// app.js
import { createApp } from '@interswitch/apex-runtime';

createApp({
  onLaunch(options) {
    console.log('App launched with:', options);
  },

  onShow() {
    console.log('App shown');
  },

  onHide() {
    console.log('App hidden');
  },

  globalData: {
    userInfo: null
  }
});
```

### Page Definition

```javascript
// pages/index/index.js
import { createPage } from '@interswitch/apex-runtime';

createPage({
  data: {
    message: 'Hello APEX!',
    count: 0
  },

  onLoad(query) {
    console.log('Page loaded with query:', query);
  },

  onShow() {
    console.log('Page shown');
  },

  onReady() {
    console.log('Page ready');
  },

  onHide() {
    console.log('Page hidden');
  },

  onUnload() {
    console.log('Page unloaded');
  },

  // Event handlers
  handleTap() {
    this.setData({
      count: this.data.count + 1
    });
  },

  // Async data update
  async fetchData() {
    const result = await apex.request({ url: '/api/data' });
    this.setData({ items: result.data });
  }
});
```

### Component Definition

```javascript
// components/button/button.js
import { createComponent } from '@interswitch/apex-runtime';

createComponent({
  properties: {
    text: {
      type: String,
      value: 'Button'
    },
    type: {
      type: String,
      value: 'default' // 'default' | 'primary' | 'danger'
    },
    disabled: {
      type: Boolean,
      value: false
    }
  },

  data: {
    pressed: false
  },

  lifetimes: {
    created() {
      console.log('Component created');
    },
    attached() {
      console.log('Component attached to page');
    },
    detached() {
      console.log('Component detached');
    }
  },

  methods: {
    handleTap() {
      if (!this.properties.disabled) {
        this.triggerEvent('tap', { timestamp: Date.now() });
      }
    }
  }
});
```

## Architecture

### Dual-Thread Model

APEX uses a dual-thread architecture to ensure 60fps UI performance:

```
┌─────────────────────────────┐          ┌─────────────────────────────┐
│       LOGIC THREAD          │          │        VIEW THREAD          │
│                             │          │                             │
│  ┌───────────────────────┐  │          │  ┌───────────────────────┐  │
│  │  JavaScriptCore / V8  │  │  JSON    │  │   WebView Renderer    │  │
│  │                       │  │  Patch   │  │                       │  │
│  │  • app.js execution   │──┼──────────┼─▶│  • AXML rendering     │  │
│  │  • State management   │  │          │  │  • DOM manipulation   │  │
│  │  • API calls          │  │          │  │  • 60fps animations   │  │
│  │  • Business logic     │◀─┼──────────┼──│  • User interactions  │  │
│  │                       │  │  Events  │  │                       │  │
│  │  NO DOM ACCESS        │  │          │  │  NO BUSINESS LOGIC    │  │
│  └───────────────────────┘  │          │  └───────────────────────┘  │
└─────────────────────────────┘          └─────────────────────────────┘
```

**Why Dual-Thread?**
- Scrolling and animations stay at 60fps regardless of JS processing
- Heavy computations don't block UI
- Better security isolation

### Runtime Components

```
┌─────────────────────────────────────────────────────────┐
│                    Mini-App Code                         │
│  (app.js, pages/*.js, components/*.js)                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                  @interswitch/apex-runtime               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ LogicThread │  │ ViewThread  │  │  Component  │     │
│  │             │  │             │  │   System    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ JSON Patch  │  │   Router    │  │   Events    │     │
│  │ (RFC 6902)  │  │             │  │             │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ Reactivity  │  │  Scheduler  │  │  Lifecycle  │     │
│  │   System    │  │             │  │   Hooks     │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                  @interswitch/apex-sdk                   │
│            (Bridge communication layer)                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Native Host App                        │
└─────────────────────────────────────────────────────────┘
```

### Runtime Usage

```javascript
import { createRuntime } from '@interswitch/apex-runtime';

const runtime = createRuntime({
  mode: 'single-thread', // or 'dual-thread' for production
  appConfig: {
    appId: 'my-app',
    version: '1.0.0',
    pages: ['/pages/index/index'],
  },
  initialRoute: '/pages/index/index',
  debug: true,
});

// Register pages
runtime.registerPage(
  '/pages/index/index',
  {
    data: { count: 0 },
    onLoad(query) {
      console.log('Page loaded', query);
    },
    handleTap() {
      this.setData({ count: this.data.count + 1 });
    },
  },
  template
);

// Start the runtime
await runtime.start();
```

## API Reference

### App Lifecycle

| Event | Description |
|-------|-------------|
| `onLaunch` | Triggered when app is launched (once) |
| `onShow` | Triggered when app comes to foreground |
| `onHide` | Triggered when app goes to background |
| `onError` | Triggered when script error occurs |
| `onPageNotFound` | Triggered when page not found |

### Page Lifecycle

| Event | Description |
|-------|-------------|
| `onLoad` | Triggered when page is loaded |
| `onShow` | Triggered when page is shown |
| `onReady` | Triggered when page rendering is complete |
| `onHide` | Triggered when page is hidden |
| `onUnload` | Triggered when page is unloaded |
| `onPullDownRefresh` | Triggered on pull-down refresh |
| `onReachBottom` | Triggered when scrolled to bottom |
| `onShareAppMessage` | Triggered when user shares |

### Component Lifecycle

| Event | Description |
|-------|-------------|
| `created` | Component instance created |
| `attached` | Component attached to page |
| `ready` | Component layout complete |
| `moved` | Component moved in tree |
| `detached` | Component detached from page |

## License

MIT