Package Exports

userscript-helpers
userscript-helpers/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (userscript-helpers) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

userscript-helpers

Helper functions for userscript with server connection.

Features

Using child window to proxy connection to custom server
Typescript support

Installation

npm install userscript-helpers

You can also install userscript-helpers with pnpm, yarn, or slnpm

Usage Example

Details see server.ts and userscript.ts

In express server:

import { attachFrameRoute } from 'userscript-helpers'
import express from 'express'

let app = express()

attachFrameRoute(app)
app.use(express.json())
app.use(express.urlencoded({ extended: false }))

let urls = new Set<string>()

app.post('/img', (req, res) => {
  let url = req.body.url
  urls.add(url)
  res.json({ count: urls.size })
})

app.listen(8100)

In userscript:

import { setupFrame, sleep } from 'userscript-helpers'

async function main() {
  let frame = await setupFrame({
    api_origin: 'http://localhost:8100',
  })
  let imgs = new Set<HTMLImageElement>()
  frame.startLoop({
    async loop() {
      let new_imgs = document.querySelectorAll('img')
      for (let img of new_imgs) {
        let url = img.src
        if (!url || imgs.has(img)) continue
        img.scrollIntoView({ behavior: 'smooth' })
        await sleep(500)
        let json = await frame.fetchJSON('POST', '/img', { url })
        console.log('post img result:', json)
        imgs.add(img)
      }
    },
  })
}

main().catch(e => console.error(e))

Typescript Signature

Server-side functions:

export function attachFrameRoute(app: Router | Application): void

Client-side functions for userscript:

export function setupFrame(options: {
  api_origin: string
  /**
   * @description overwrite `console.log()` and `console.error()` by `console.debug()`
   */
  wrap_console?: boolean
}): Promise<{
  proxyWindowPromise: Promise<Window>
  callAPI: <T>(url: string, init: RequestInit) => Promise<T>
  fetchJSON: <T>(method: string, url: string, body?: object) => Promise<T>
  postForm: <T>(url: string, formData: FormData) => Promise<T>
  startLoop: (options: {
    loop(): LoopResult | Promise<LoopResult>
    /**
     * @description default 1000
     */
    loop_interval?: number
    /**
     * @description default 3500
     */
    error_retry_interval?: number
  }) => void
  isCurrentIteration: () => boolean
  stopIteration: (context?: string) => void
}>

export type LoopResult = void | 'stop'

export declare function imageToDataUrl(
  img: HTMLImageElement,
  /** @description default is as-is for image with dataUrl, and "image/png" for image with src */
  mimeType?: ImageMimeType,
  /** @description between 0 and 1 */
  quality?: number,
): Promise<string>

export type ImageMimeType = 'image/png' | 'image/jpeg' | 'image/webp'

Additional helper functions for any side:

/**
 * @description async version of setTimeout
 */
export function sleep(ms: number): Promise<void>

/**
 * @returns mimetype, e.g. "image/webp"
 */
export function dataUrlToMimeType(dataUrl: string): string

/**
 * @return extname without ".", e.g. "webp"
 */
export function dataUrlToExtname(dataUrl: string): string

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

The freedom to run the program as you wish, for any purpose
The freedom to study how the program works, and change it so it does your computing as you wish
The freedom to redistribute copies so you can help others
The freedom to distribute copies of your modified versions to others