make-synchronized

Make synchronized functions.

Install

yarn add make-synchronized

Usage

This module mainly to support three kinds of different purpose of usage:

1. Make asynchronous functions in an existing module into synchronized

   import makeSynchronized from 'make-synchronized'
   
   const synchronized = makeSynchronized(
     new URL('./my-asynchronous-function-module.js', import.meta.url),
   )
   

2. Make a module that turns asynchronous function into synchronized

   import makeSynchronized from 'make-synchronized'
   
   export default makeSynchronized(import.meta, myAsynchronousFunction)
   

3. Make an inline asynchronous function into synchronized

   import makeSynchronized from 'make-synchronized'
   
   const synchronized = makeSynchronized(() => Promise.resolve('foo'))
   

Named exports

import {
  makeSynchronized, // Same as the default export
  makeDefaultExportSynchronized,
  makeModuleSynchronized,
  makeSynchronizedFunction,
  makeSynchronizedFunctions,
  makeInlineFunctionSynchronized,
} from 'make-synchronized'

Limitation

This module uses MessagePort#postMessage to transfer arguments, return values, errors between the main thread and the worker. Please make sure the arguments and return values are serializable by the structured clone algorithm.

API

makeSynchronized(module: string | URL | ImportMeta)

Make asynchronous functions in an existing module to be synchronized to call.

• If the passing module is a module that contains a function type default export, returns a Proxy function, with other specifiers attached.

  // foo.js
  export default () => Promise.resolve('default export called')
  export const foo = 'foo'
  export const bar = () => Promise.resolve('bar called')
  

  const synchronized = makeSynchronized(new URL('./foo.js', import.meta.url))
  
  synchronized()
  // -> "default export called"
  
  synchronized.foo
  // -> "foo"
  
  // This function also synchronized.
  synchronized.bar()
  // -> "bar called"
  

  Example

• If the passing module is a module without default export or default export is not a function, a Module object will be returned with all specifiers.

  // foo.js
  export const foo = 'foo'
  export const bar = () => Promise.resolve('bar called')
  

  import makeSynchronized from 'make-synchronized'
  
  const module = makeSynchronized(new URL('./foo.js', import.meta.url))
  
  module
  // [Object: null prototype] [Module] { bar: [Getter], foo: [Getter] }
  
  module.foo
  // -> "foo"
  
  module.bar()
  // -> "bar called"
  

  Example

makeSynchronized(module: string | URL | ImportMeta, implementation: function | object)

Make asynchronous functions to be synchronized for export.

• If implementation is a function, returns a synchronized version of the passed function.

  [!IMPORTANT]

  It MUST be used as the default export

  // foo.js
  import makeSynchronized from 'make-synchronized'
  
  export default makeSynchronized(import.meta, () => Promise.resolve('foo'))
  

  import foo from './foo.js'
  
  foo()
  // -> foo
  

  • Example

• If implementation is a object with multiple functions, returns a Proxy object with synchronized functions attached.

  [!IMPORTANT]

  Functions MUST exported as the same name as the key in implementation object.

  // foo-and-bar.js
  import makeSynchronized from 'make-synchronized'
  
  export const {foo, bar} = makeSynchronized(import.meta, {
    async foo() {
      return 'foo'
    },
    async bar() {
      return 'bar'
    },
  })
  

  import {foo, bar} from './foo-and-bar.js'
  
  foo()
  // -> foo
  
  bar()
  // -> bar
  

• Example

makeSynchronized(implementation: function)

import makeSynchronized from 'make-synchronized'

const foo = makeSynchronized(() => Promise.resolve('foo'))

foo()
// -> foo

[!IMPORTANT]

The given function is executed in a separate environment, so you cannot use any variables/imports from outside the scope of the function. You can pass in arguments to the function. To import dependencies, use await import(…) in the function body.

• Example

makeSynchronizedFunction(module: string | URL | ImportMeta, implementation: function, specifier?: string)

Make a synchronized function for export.

Explicit version of makeSynchronized(module, implementation) that returns the synchronized function for export.

import {makeSynchronizedFunction} from 'make-synchronized'

export default makeSynchronizedFunction(
  import.meta,
  async () => 'default export called',
)
export const foo = makeSynchronizedFunction(
  import.meta,
  async () => 'foo export called',
  'foo',
)

makeSynchronizedFunctions(module: string | URL | ImportMeta, implementation: object)

Make synchronized functions for export.

Explicit version of makeSynchronized(module, implementation) that only returns Proxy with synchronized functions for export.

import {makeSynchronizedFunctions} from 'make-synchronized'

export const {
  // MUST match the key in second argument
  foo,
  bar,
} = makeSynchronizedFunctions(import.meta, {
  foo: async () => 'foo export called',
  bar: async () => 'bar export called',
})

makeDefaultExportSynchronized(module: string | URL | ImportMeta)

Make an existing module's default export to be a synchronized function.

Explicit version of makeSynchronized(module) that only returns the synchronized default export.

import {makeDefaultExportSynchronized} from 'make-synchronized'

const foo = makeModuleSynchronized('foo')

foo()
// -> default export of `foo` module is called.

makeModuleSynchronized(module: string | URL | ImportMeta)

Make an existing module's exports to be synchronized functions.

Synchronize version of import(module), always returns a Module.

- const {default: foo} = await import('foo')
+ const {default: foo} = makeModuleSynchronized('foo')

import {makeModuleSynchronized} from 'make-synchronized'

const {default: foo, bar} = makeModuleSynchronized('foo')

foo()
// -> default export of `foo` module is called.

bar()
// -> `bar` function from `foo` module is called.

makeInlineFunctionSynchronized(implementOrCode: function | string)

Make an inline asynchronous function into synchronized.

[!IMPORTANT]

The given function is executed in a separate environment, so you cannot use any variables/imports from outside the scope of the function. You can pass in arguments to the function. To import dependencies, use await import(…) in the function body.

Explicit version of makeSynchronized(function).

import makeSynchronized from 'make-synchronized'

const foo = makeSynchronized(() => Promise.resolve('foo'))

foo()
// -> foo

import makeSynchronized from 'make-synchronized'

const foo = makeSynchronized(`
  () => ${someOtherCode}
`)

foo()

import makeSynchronized from 'make-synchronized'

const sleep = makeSynchronized((delay) =>
  process.getBuiltinModule('node:timers/promises').setTimeout(delay),
)

import makeSynchronized from 'make-synchronized'

const sleep = makeSynchronized(async (delay) => {
  const {setTimeout} = await import('node:timers/promises')
  await setTimeout(delay)
})