@hypernym/frame

Universal Frame Manager.

Repository ✦ Package ✦ Releases ✦ Discussions

pnpm add @hypernym/frame

_{Package size: ~1.28 KB minified, ~705 B 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 Controls
• FPS Managment
• 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 },
)

Each phase is executed in strictly ascending numerical order.

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'

// Frame
const frame = createFrame(options)

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

// Controls
frame.start()
frame.stop()

// Getters/Setters
frame.state
frame.fps

add

• Type: (process: Process, options?: ProcessOptions): Process

Adds a specific process to the frame update cycle.

By default, the process will be executed only once.

frame.add(process, options)

delete

• Type: (process?: Process): void

Deletes a specific process from the frame update cycle.

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

start

• Type: (): void

Starts the entire frame loop.

frame.start()

stop

• Type: (): void

Stops the entire frame loop.

frame.stop()

loop

• Type: boolean
• Default: undefined

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

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

phase

• Type: number
• Default: 0

Specifies a custom frame phase.

Phases always run in strictly ascending numerical order.

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
// ...

schedule

• Type: boolean
• Default: true

Specifies the scheduling behavior.

By default, the process waits for the next loop cycle. If disabled, it cancels the scheduling to the next frame and executes at the end of the current frame.

let index = 0

frame.add(() => {
  index++
  frame.add(() => index++, { schedule: false })
})
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, setTimeout or microtask.

import { createFrame } from '@hypernym/frame'

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

fps

• Type: number
• Default: undefined

Specifies a fixed rate for the frame update cycle.

By default, the frame runs as fast as possible (typically tied to the raf cycle, which is usually 60 FPS or higher).

import { createFrame } from '@hypernym/frame'

const frame = createFrame({ fps: 60 })

// Specifies the `fps` via setter
frame.fps = 60

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.