JOYCO Susano

Asset load orchestration made easy.

pnpm add @joycostudio/susano

Quick Start

import { susano } from '@joycostudio/susano'

// Queue assets
susano.add('/hero.png', { type: 'image' })
susano.add('/intro.mp4', { type: 'video' })

// Start loading
susano.start({
  onProgress: ({ value }) => console.log(`${Math.round(value * 100)}%`),
  onCompleted: () => console.log('All assets loaded!'),
})

API

susano singleton

A pre-configured instance with built-in loaders for image, video, audio, and generic types.

add(url, { type, loaderArgs? })

Queue an asset for batch loading. Returns the loader instance.

const img = susano.add('/photo.png', {
  type: 'image',
  loaderArgs: { srcSet: '480w.png 480w, 800w.png 800w', sizes: '(max-width: 600px) 480px, 800px' },
})

load(url, { type, loaderArgs? })

Load a single asset immediately (standalone, outside the batch queue). Returns the loader instance.

const img = susano.load('/standalone.png', { type: 'image' })

start({ onProgress?, onCompleted? })

Start loading all queued assets. Emits start, progress, and completed events.

susano.start({
  onProgress: ({ value, item }) => {
    // value: 0 to 1
  },
  onCompleted: (susano) => {
    // all assets loaded
  },
})

registerLoader(type, loader)

Register a custom loader class for a given type.

susano.registerLoader('custom', CustomLoader)

Built-in Loaders

image

Loads images via HTMLImageElement.

| Option | Type | Description | | -------- | -------- | ----------------------------- | | srcSet | string | Maps to img.srcset | | sizes | string | Maps to img.sizes |

susano.add('/photo.png', {
  type: 'image',
  loaderArgs: { srcSet: '/photo-2x.png 2x', sizes: '100vw' },
})

video

Loads video via HTMLVideoElement.

| Option | Type | Default | Description | | ----------- | ---------------------------------- | ----------- | ---------------------------------- | | video | HTMLVideoElement | new element | Existing video element to load into | | loadEvent | 'canplay' | 'canplaythrough' | 'canplay' | Event that signals load completion |

susano.add('/intro.mp4', {
  type: 'video',
  loaderArgs: { loadEvent: 'canplaythrough' },
})

audio

Loads audio via HTMLAudioElement.

| Option | Type | Default | Description | | ----------- | ---------------------------------- | ----------- | ---------------------------------- | | audio | HTMLAudioElement | new element | Existing audio element to load into | | loadEvent | 'canplay' | 'canplaythrough' | 'canplay' | Event that signals load completion |

susano.add('/music.mp3', {
  type: 'audio',
  loaderArgs: { loadEvent: 'canplaythrough' },
})

generic

Fully custom loader. Requires a loadFn callback.

| Option | Type | Description | | -------- | ------------- | ------------------------------------ | | loadFn | GenericLoadFn | Required. Custom load function |

The loadFn receives { url, done, error, progress }:

susano.add('/data.json', {
  type: 'generic',
  loaderArgs: {
    loadFn: ({ url, done, error, progress }) => {
      fetch(url)
        .then((res) => res.json())
        .then((data) => done(data))
        .catch((err) => error(err))
    },
  },
})

Events

The susano instance extends TinyEmitter and emits:

| Event | Payload | Description | | ----------- | ---------------------------------------------------- | ------------------------- | | start | susano | Batch loading started | | progress | { value: number, item: SusanoLoader, susano } | An asset finished loading | | completed | susano | All assets loaded |

Individual loader instances also emit loaded and progress events.

Batched vs Standalone Loading

Batched — queue multiple assets with add(), then call start() to load them all. Progress is tracked across the entire batch.

susano.add('/a.png', { type: 'image' })
susano.add('/b.mp4', { type: 'video' })
susano.start({ onCompleted: () => console.log('done') })

Standalone — use load() to immediately load a single asset without affecting the batch queue.

const item = susano.load('/lazy.png', { type: 'image' })

🤖 Automatic Workflows

1. Release Workflow (.github/workflows/release.yml): Automates the release process using Changesets. When enabled, it will automatically create release pull requests and publish to npm when changes are pushed to the main branch.

2. Publish Any Commit (.github/workflows/publish-any-commit.yml): A utility workflow that can build and publish packages for any commit or pull request.

🦋 Version Management

This library uses Changesets to manage versions and publish releases. Here's how to use it:

Adding a changeset

When you make changes that need to be released:

pnpm changeset

This will prompt you to:

1. Select which packages you want to include in the changeset
2. Choose whether it's a major/minor/patch bump
3. Provide a summary of the changes

Creating a release

To create a new version and update the changelog:

# 1. Create new versions of packages
pnpm version:package

# 2. Release (builds and publishes to npm)
pnpm release

Remember to commit all changes after creating a release.