# rycursiv/hammerspoon-promise architecture

> Architecture diagram of the GitHub repository rycursiv/hammerspoon-promise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rycursiv/hammerspoon-promise
- Repository: https://github.com/rycursiv/hammerspoon-promise

## Overview

##### Project type and purpose
- Type: A standalone Lua module providing Promise/A+-style asynchronous programming primitives for Hammerspoon.
- Purpose: Offer `Promise`, `async`/`await`, fetch helpers (`Promise.fetch`, `Promise.fetchImg`), plus combinators (`all`, `race`, etc.) on top of Hammerspoon’s event loop and HTTP/image APIs.

##### File structure
- Single top-level file `promise.lua` containing the entire implementation.
- No subdirectories—this is a self-contained library.
- README outlines the public API and usage patterns.

##### README for insights
- Public constructors: `Promise(executor)` / `Promise.new(executor)`.
- Static helpers: `resolve`, `reject`, `all`, `race`, `sleep`, `fetch`, `fetchImg`, `async`, `await`, etc.
- Instance methods: `:next()`, `:catch()`, `:finally()`.
- Under the hood it schedules resolution/rejection via Hammerspoon’s event loop and wraps `hs.http.doAsyncRequest` and `hs.image.imageFromURL`.

##### Main components
a. User Script (Client)
– Invokes `Promise.new`, `Promise.async`, or any static helper.
– Chains `.next()`, `.catch()`, `.finally()`.
b. Promise Core (Library)
– Executor function + internal state machine (pending → fulfilled/rejected).
– Callback queues for onFulfilled, onRejected, onFinally.
– Static combinators (all, race, allSettled, any).
– Sugar methods: `sleep`, `fetch`, `fetchImg`, `async`, `await`.
c. Hammerspoon Runtime
– Event loop: delivers callbacks back to the Lua VM.
– `hs.http.doAsyncRequest`: underlying HTTP.
– `hs.image.imageFromURL`: underlying image fetch.
d. External Services (optional)
– Remote HTTP endpoints invoked by `Promise.fetch`.
– Image servers used by `Promise.fetchImg`.

##### Relationships and interactions
- User → Promise Core: calls constructors, static methods, instance methods.
- Promise Core → Hammerspoon APIs:
– `fetch()` → `hs.http.doAsyncRequest` → onResponse callback → resolve/reject promise.
– `fetchImg()` → `hs.image.imageFromURL` → resolve with `hs.image` object.
- Promise Core → internal scheduler → Hammerspoon event loop → deferred invocation of handlers.
- Promise Core combinators (e.g. `Promise.all`) orchestrate multiple inner promises.

##### Architectural patterns and design principles
- State machine pattern: pending/fulfilled/rejected.
- Chainable interface: each `.next()` returns a new Promise.
- Functional combinators: `all`, `race`, `any`, `allSettled`.
- Async/await sugar: `Promise.async` wraps a function to allow `Promise.await`.

##### Detailed elements
- “Scheduler / Event Loop” connector illustrating how callbacks are deferred.
- “Async/Await Sugar” showing `Promise.async(fn)` and `Promise.await(value)`.
- Life cycle: User calls `Promise.async(fn)()` → inside fn calls `await(p)` → the runtime suspends, schedules, resumes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Script"
        US["User Script"]:::user
    end

    %% Promise Core Layer
    subgraph "Promise Core"
        PC1["Constructor / Executor"]:::core
        PC2["State Machine"]:::core
        PC3["Callback Queues"]:::core
        PC4["Static Combinators<br/>all, race, any, allSettled"]:::core
        PC5["Sugar Helpers<br/>sleep, fetch, fetchImg, async, await"]:::core
        PC6["Public API Exports"]:::core
    end

    %% Hammerspoon APIs Layer
    subgraph "Hammerspoon APIs"
        HS1["hs.http.doAsyncRequest"]:::hs
        HS2["hs.image.imageFromURL"]:::hs
        HS3["Event Loop / Scheduler"]:::hs
    end

    %% External Services Layer
    subgraph "External Services"
        ES1["HTTP Server"]:::external
        ES2["Image Server"]:::external
    end

    %% Docs & Config Layer
    subgraph "Docs & Config"
        RD1["README Documentation"]:::docs
        RD2["Project Metadata"]:::docs
        LIC["License Information"]:::docs
        GI["Version Control Ignored Files (.gitignore)"]:::docs
    end

    %% Connections
    US -->|"calls Promise.new / .async / static helpers"| PC1
    PC1 -->|"initialize state"| PC2
    PC2 -->|"register callbacks"| PC3
    PC3 -->|"expose methods"| PC6
    PC6 -->|"invoke combinators"| PC4
    PC6 -->|"invoke sugar helpers"| PC5

    PC5 -->|"fetch() → doAsyncRequest"| HS1
    PC5 -->|"fetchImg() → imageFromURL"| HS2
    PC3 -.->|"deferred callbacks"| HS3

    HS1 -->|"HTTP request"| ES1
    HS2 -->|"image download"| ES2
    HS3 -->|"invoke handlers"| PC3

    RD1 --- US
    RD2 --- PC6
    LIC --- PC6
    GI --- PC6

    %% Click Events
    click PC1 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click PC2 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click PC3 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click PC4 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click PC5 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click PC6 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click HS1 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click HS2 "https://github.com/rycursiv/hammerspoon-promise/blob/main/promise.lua"
    click RD1 "https://github.com/rycursiv/hammerspoon-promise/blob/main/README.md"
    click RD2 "https://github.com/rycursiv/hammerspoon-promise/blob/main/README.md"
    click LIC "https://github.com/rycursiv/hammerspoon-promise/tree/main/LICENSE"
    click GI "https://github.com/rycursiv/hammerspoon-promise/blob/main/.gitignore"

    %% Styles
    classDef user fill:#D0E5FF,stroke:#000,stroke-width:1px
    classDef core fill:#D0F0C0,stroke:#000,stroke-width:1px
    classDef hs fill:#FFD580,stroke:#000,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#000,stroke-width:1px
    classDef docs fill:#EEEEEE,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
