Susano

pnpm add @joycostudio/susano

import { susano } from '@joycostudio/susano'
 
const batch = susano.batch(
  [
    { url: '/hero.png', type: 'image' },
    { url: '/intro.mp4', type: 'video' },
    { url: '/music.mp3', type: 'audio' },
  ],
  {
    onProgress: ({ value }) => console.log(`${Math.round(value * 100)}%`),
    onCompleted: () => console.log('All assets loaded!'),
  }
)
 
await batch.promise

import { useEffect, useState } from 'react'
import { susano, type BatchProgressEventArgs } from '@joycostudio/susano'
 
function App() {
  const [progress, setProgress] = useState(0)
 
  useEffect(() => {
    susano.batch(
      [
        { url: '/hero.png', type: 'image' },
        { url: '/intro.mp4', type: 'video' },
      ],
      { onProgress: ({ value }: BatchProgressEventArgs) => setProgress(value) }
    )
  }, [])
 
  return <div>Loading: {Math.round(progress * 100)}%</div>
}

import { susano } from '@joycostudio/susano'

import { Susano, ImageLoader, VideoLoader, AudioLoader, GenericLoader } from '@joycostudio/susano'
 
const s = new Susano({
  image: ImageLoader,
  video: VideoLoader,
  audio: AudioLoader,
  generic: GenericLoader,
})
 
s.load('/x.png', { type: 'image' }) // `type` is 'image' | 'video' | 'audio' | 'generic'

const s = new Susano({ image: ImageLoader, json: JSONLoader })
//                                          ^ adds 'json' as a valid type, fully typed

susano.load(url, {
  type,                 // which loader
  loaderArgs?,          // construction: how to produce the content (srcSet, loadEvent, loadFn…)
  cache?,               // false → force a fresh content fetch (default true)
  postprocess?,         // per call: (content, loader) => R | Promise<R>
  onLoaded?,            // per call: (result, loader) => void
  onProgress?,          // observes the shared content fetch: (value, loader) => void
  onError?,             // per call: (error, loader) => void
})

const bitmap = await susano.load('/hero.png', {
  type: 'image',
  postprocess: async (img) => createImageBitmap(img),
}) // ImageBitmap (this call's result)
 
susano.get('/hero.png')?.content // the shared HTMLImageElement (cached)

const batch = susano.batch(
  [
    { url: '/studio.glb', type: 'gltf', postprocess: parseScene },
    { url: '/env.exr', type: 'exr' },
    { url: '/noise.png', type: 'texture', cache: false },
  ],
  { onProgress, onCompleted, onError }
)

type BatchHandlers = {
  onProgress?: (e: BatchProgressEventArgs) => void  // { value, loader, batch }
  onCompleted?: (batch: Batch) => void
  onError?: (e: BatchErrorEventArgs) => void         // { loader, error, batch }
}

susano.load('/photo.png', { type: 'image' })
const loader = susano.get('/photo.png')!
loader.on('loaded', (l) => console.log(l.content))
loader.on('error', (err) => console.error(err))

const bitmap: ImageBitmap = await susano.load('/hero.png', {
  type: 'image',
  postprocess: async (img) => createImageBitmap(img),
})

import { ImageLoader, type SusanoImageLoaderConfig } from '@joycostudio/susano'

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

import { VideoLoader, AudioLoader } from '@joycostudio/susano'

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

import { GenericLoader, type GenericLoadFn } from '@joycostudio/susano'
 
type GenericLoadFn = (ctx: {
  url: string
  done: (content: any) => void
  error: (error: Error) => void
  progress: (value: number) => void // 0 → 1
}) => void

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

const img = susano.load('/hero.png', { type: 'image' })
document.body.appendChild(await img.promise)

const [a, b] = await Promise.all([
  susano.load('/a.png', { type: 'image' }),
  susano.load('/b.mp4', { type: 'video' }),
])
// …or drive a progress bar with a batch over the same URLs (dedupes the fetches):
await susano.batch([
  { url: '/a.png', type: 'image' },
  { url: '/b.mp4', type: 'video' },
]).promise

// Both share one /noise.png fetch; each gets its own result.
const bitmap = await susano.load('/noise.png', { type: 'image', postprocess: (i) => createImageBitmap(i) })
const raw = await susano.load('/noise.png', { type: 'image' }) // raw HTMLImageElement, shared fetch

susano.load('/big.bin', {
  type: 'generic',
  loaderArgs: {
    loadFn: async ({ url, done, error, progress }) => {
      try {
        const res = await fetch(url)
        const total = Number(res.headers.get('content-length')) || 0
        const reader = res.body!.getReader()
        const chunks: Uint8Array[] = []
        let received = 0
        while (true) {
          const { done: d, value } = await reader.read()
          if (d) break
          chunks.push(value)
          received += value.length
          if (total) progress(received / total)
        }
        done(new Blob(chunks))
      } catch (e) {
        error(e as Error)
      }
    },
  },
})

import { Susano, SusanoLoader } from '@joycostudio/susano'
 
class JSONLoader extends SusanoLoader<unknown> {
  protected _load() {
    fetch(this.url)
      .then((res) => res.json())
      .then((content) => {
        this.content = content
        this._onLoaded()
      })
      .catch((e) => this._onError(e))
  }
}
 
const s = new Susano({ json: JSONLoader })
 
await s.batch([{ url: '/config.json', type: 'json' }]).promise

susano.load('/hero.png', { type: 'image' }) // fires immediately
const batch = susano.batch([{ url: '/hero.png', type: 'image' }]) // joins it — no second fetch
 
await batch.promise
susano.get('/hero.png') // the one shared content loader both used

pnpm install
pnpm test          # Vitest suite (run); pnpm test:watch for watch mode
pnpm typecheck     # tsc --noEmit
pnpm build         # tsup bundle