@hypernym/frame

Universal Frame Manager.

Repository | Package | Releases | Discussions

pnpm add @hypernym/frame

_{Size: ~1.01 KB min, ~0.58 KB gzip}

Features

• Ultra Lightweight & Powerful
• Framework Independent
• Written in TypeScript
• Native SSR Support
• No External Dependencies
• API Friendly

Core Concepts

• Frame Scheduling
• Dynamic Phases
• Strict Queue Order
• Custom Scheduler
• Frame State
• Modular Code
• Type-safe

Installation

pnpm add @hypernym/frame

npm install @hypernym/frame

CDN

ESM (minified)

<script type="module">
  import { createFrame } from 'https://unpkg.com/@hypernym/frame/dist/index.min.js'
  const frame = createFrame()
</script>

IIFE (minified)

<script src="https://unpkg.com/@hypernym/frame/dist/index.iife.js"></script>
<script>
  const { createFrame } = Frame
  const frame = createFrame()
</script>

UMD (minified)

<script src="https://unpkg.com/@hypernym/frame/dist/index.umd.js"></script>
<script>
  const { createFrame } = Frame
  const frame = createFrame()
</script>

Quick Start

Creates a frame manager with the default phase.

import { createFrame } from '@hypernym/frame'

const frame = createFrame()

let index = 0

// Adds a custom process to the `default` phase and enables looping
const process = frame.add(
  (state) => {
    index++
    console.log('Process Loop', index)

    if (index > 100) {
      frame.delete(process)
      console.log('Process Loop: Done!', state)
    }
  },
  { loop: true },
)

Phases always run from the lowest number to the highest.

frame.add(() => console.log('Phase 2: Render'), { phase: 2 })
frame.add(() => console.log('Phase 1: Update'), { phase: 1 })
frame.add(() => console.log('Phase 0: Read'))
frame.add(() => console.log('Phase 2: Render'), { phase: 2 })
frame.add(() => console.log('Phase 0: Read'))
frame.add(() => console.log('Phase 1: Update'), { phase: 1 })

Output:

Phase 0: Read
Phase 0: Read
Phase 1: Update
Phase 1: Update
Phase 2: Render
Phase 2: Render

API

import { createFrame } from '@hypernym/frame'

// Main Frame
const frame = createFrame(options)

// Methods
frame.add(process, options)
frame.delete(process)

// Getters
frame.state

add

• Type: (process: FrameProcess, options?: FrameProcessOptions): FrameProcess

Adds a specific process to the frame update cycle.

Note

By default, the process will be executed only once (phase: 0).

frame.add(process, options)

loop

• Type: boolean
• Default: undefined

Specifies whether the phase process should continue to repeat, without stopping after the first execution.

Note

Repeating processes need to be removed manually using the frame.delete(process) method.

frame.add((state) => console.log(state), { loop: true })

delete

• Type: (process?: FrameProcess): void

Deletes a specific process from the frame update cycle.

Note

Calling frame.delete() without the process parameter resets the main frame instance, resulting in the deletion of all processes, phases, and state.

frame.delete(process) // Deletes a specific process
frame.delete() // Deletes all processes, phases and resets the frame state

phase

• Type: number
• Default: 0

Specifies a custom frame phase.

Phases are processed in ascending numerical order, meaning lower run before higher ones.

frame.add(process, { phase: -1 }) // Runs before 0
frame.add(process) // Default phase is 0
frame.add(process, { phase: 1 }) // Runs after 0
frame.add(process, { phase: 2 }) // Runs after 1
// ...

immediate

• Type: boolean
• Default: undefined

Controls the scheduling behavior.

By default, the process is scheduled to the next loop cycle. When enabled, it skips scheduling and executes at the end of the current frame.

let index = 0

frame.add(() => {
  index++
  frame.add(() => index++, { immediate: true })
})
frame.add(() => console.log('Index: ', index), { phase: 1 }) // => Index 2

state

• Type: object

Provides read‑only info about the frame’s internal state at any given point.

frame.add((state) => console.log(state))

// Gets the `state` via getter
console.log(frame.state)

Options

scheduler

• Type: (process: VoidFunction) => number | void
• Default: requestAnimationFrame

Specifies the scheduling system for the frame cycle.

Determines how the frame updates are processed, whether through the requestAnimationFrame or microtask.

import { createFrame } from '@hypernym/frame'

const frame = createFrame({ scheduler: queueMicrotask, loop: false })

loop

• Type: boolean
• Default: true

Specifies global looping across all processes.

import { createFrame } from '@hypernym/frame'

const frame = createFrame({ loop: false })

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.