npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

tail-call-proxy

v1.1.12

Published

A template for creating npm packages using TypeScript and VSCode

Downloads

19

Readme

tail-call-proxy

Delayed initialized objects that support tail-call optimization.

npm package Build Status Downloads Issues Code Coverage Commitizen Friendly Semantic Release

Functions

lazy

lazy<T>(tailCall): T

Returns an proxy object backed by tailCall, which will be lazily created at the first time its properties or methods are used.

lazy can eliminate tail calls, preventing stack overflow errors in tail recursive functions or mutual recursive functions.

Example

The initializer passed to lazy should not be called until the first time lazyObject.hello is accessed. When lazyObject.hello is accessed more than once, the second access would not trigger the initializer again.

import { lazy } from 'tail-call-proxy';

let counter = 0;
const lazyObject = lazy(() => {
  counter++;
  return { hello: 'world' };
});
expect(counter).toBe(0);

expect(lazyObject.hello).toBe('world');
expect(counter).toBe(1);

expect(lazyObject.hello).toBe('world');
expect(counter).toBe(1);

Example

Note that errors thrown in the initializer will be delayed as well.

import { lazy } from 'tail-call-proxy';

let counter = 0;
const lazyError: Record<string, unknown> = lazy(() => {
  counter++;
  throw new Error();
});

// No error is thrown, given that the underlying object have not been created
// yet.
expect(counter).toBe(0);

expect(() => lazyError.toString()).toThrow();
expect(counter).toBe(1);

expect(() => lazyError.toLocaleString()).toThrow();
expect(counter).toBe(1);

Example

The following mutual recursive functions would result in stack overflow:

function isEven(n: number): Boolean {
  if (n === 0) {
    return new Boolean(true);
  }
  return isOdd(n - 1);
}

function isOdd(n: number): Boolean {
  if (n === 0) {
    return new Boolean(false);
  }
  return isEven(n - 1);
}

expect(() => isOdd(1000000)).toThrow();

However, if you replace return xxx with return lazy(() => xxx), it will use a constant size of stack memory and avoid the stack overflow.

import { lazy } from 'tail-call-proxy';
function isEven(n: number): Boolean {
  if (n === 0) {
    return new Boolean(true);
  }
  return lazy(() => isOdd(n - 1));
}

function isOdd(n: number): Boolean {
  if (n === 0) {
    return new Boolean(false);
  }
  return lazy(() => isEven(n - 1));
}

expect(isOdd(1000000).valueOf()).toBe(false);

Type parameters

| Name | Type | | :------ | :------ | | T | extends object |

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | tailCall | () => T | the function to create the underlying object |

Returns

T

Defined in

index.ts:253


parasitic

parasitic<T>(tailCall): T

Performs a tail call as soon as possible.

parasitic returns either exactly the object returned by tailCall, or a proxy object backed by the object returned by tailCall, if there are any previously started pending tail calls. In the latter case, the underlying object will be created after all the previous tail calls are finished.

Example

Unlike lazy, parasitic performs the initialization as soon as possible:

import { parasitic } from 'tail-call-proxy';

let counter = 0;
const parasiticObject = parasitic(() => {
  counter++;
  return { hello: 'world' };
});
expect(counter).toBe(1);

expect(parasiticObject.hello).toBe('world');
expect(counter).toBe(1);

expect(parasiticObject.hello).toBe('world');
expect(counter).toBe(1);

Example

parasitic is useful when you need tail call optimization while you don't need the lazy evaluation. It can be used together with lazy alternately.

import { lazy, parasitic } from 'tail-call-proxy';

let isEvenCounter = 0;
const trueObject = new Boolean(true);
function isEven(n: number): Boolean {
  isEvenCounter++;
  if (n === 0) {
    return trueObject;
  }
  return lazy(() => isOdd(n - 1));
};

let isOddCounter = 0;
const falseObject = new Boolean(false);
function isOdd(n: number): Boolean {
  isOddCounter++;
  if (n === 0) {
    return falseObject;
  }
  return parasitic(() => isEven(n - 1));
};

try {
  // `isEven` is called, but `lazy(() => isOdd(n - 1))` does not trigger
  // `isOdd` immediately.
  const is1000000Even = isEven(1000000);
  expect(isOddCounter).toBe(0);
  expect(isEvenCounter).toBe(1);

  // `valueOf` triggers the rest of the recursion.
  expect(is1000000Even.valueOf()).toBe(true);
  expect(isOddCounter).toBe(500000);
  expect(isEvenCounter).toBe(500001);

  // `is1000000Even` is a lazy proxy backed by `trueObject`, not the exactly
  // same object of `trueObject`.
  expect(is1000000Even).not.toStrictEqual(trueObject);
  expect(is1000000Even).toEqual(trueObject);
} finally {
  isEvenCounter = 0;
  isOddCounter = 0;
}

// `isOdd` is called, in which `parasitic(() => isEven(n - 1))` triggers the
// rest of the recursion immediately.
const is1000000Odd = isOdd(1000000);
expect(isOddCounter).toBe(500001);
expect(isEvenCounter).toBe(500000);
expect(is1000000Odd.valueOf()).toBe(false);
expect(isOddCounter).toBe(500001);
expect(isEvenCounter).toBe(500000);

// `is1000000Odd` is exactly the same object of `falseObject`, not a lazy
// proxy.
expect(is1000000Odd).toStrictEqual(falseObject);

Type parameters

| Name | Type | | :------ | :------ | | T | extends object |

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | tailCall | () => T | the function to create the underlying object |

Returns

T

Defined in

index.ts:353