@toa.io/extensions.cadence 1.0.0-alpha.284

package/transpiled/Pulse.js

@@ -0,0 +1,148 @@
+import { console } from 'openspan';
+import { Connector } from '@toa.io/core';
+/**
+ * A recurring call to an operation of its own component, on the cadence its manifest states.
+ *
+ * Nothing is stored. The cycle is split into `n` intervals and the current one is a function of
+ * the clock, so every replica computes the same `i` without talking to any other; the one that
+ * owns `i` is the one that calls. An interval no replica was alive for is not made up
+ * afterwards — the operation is expected to select by what is still due rather than by where
+ * the cycle has reached.
+ */
+export class Pulse extends Connector {
+    endpoint;
+    label;
+    /** milliseconds one whole cycle takes */
+    cycle;
+    /** intervals the cycle is split into */
+    n;
+    local;
+    atom;
+    /** span options, built once */
+    options;
+    /**
+     * The ordinal of the interval this process has already handled, so an early wake-up is not a
+     * second call. An ordinal and not an index: with one interval per cycle the index never
+     * changes, and comparing it would suppress every call after the first.
+     */
+    fired = 0;
+    timer;
+    /** the call in flight, awaited on close */
+    firing;
+    closing = false;
+    constructor(definition, local, atom) {
+        super();
+        const { locator, endpoint, cycle, intervals } = definition;
+        this.endpoint = endpoint;
+        this.label = `${locator.id}.${endpoint}`;
+        this.cycle = cycle * 1000;
+        this.n = intervals;
+        this.local = local;
+        this.atom = atom;
+        this.depends(local);
+        this.depends(atom);
+        this.options = {
+            name: `${this.label} pulse`,
+            kind: 'producer',
+            service: locator.id
+        };
+    }
+    /**
+     * How many intervals have passed since the epoch, `now` included. Against the cycle rather
+     * than by adding up gaps, so a cycle that does not divide evenly into its intervals neither
+     * drifts nor accumulates error.
+     *
+     * The arithmetic is exact rather than double: `now` is milliseconds since 1970 and `n` may be
+     * as large as the cycle has seconds, so their product leaves the range a double is exact in
+     * for a long cycle cut finely. It is evaluated once per interval, where this costs nothing.
+     */
+    ordinal(now) {
+        return Number(BigInt(now) * BigInt(this.n) / BigInt(this.cycle));
+    }
+    /** Which of the cycle's intervals `now` falls in. */
+    index(now) {
+        return this.ordinal(now) % this.n;
+    }
+    /** When the interval `now` falls in gives way to the next one. */
+    boundary(now) {
+        const cycle = BigInt(this.cycle);
+        const n = BigInt(this.n);
+        const next = BigInt(this.ordinal(now) + 1);
+        // the earliest millisecond whose ordinal is the next one
+        return Number((next * cycle + n - 1n) / n);
+    }
+    async open() {
+        // whatever interval it is now, this replica was not there when it began, so it is not
+        // this one's to call — the first call is at the next boundary
+        this.fired = this.ordinal(Date.now());
+        this.arm();
+    }
+    async close() {
+        this.closing = true;
+        clearTimeout(this.timer);
+        // a call still running holds the remote it was made through, which is torn down after
+        // this returns. Bounded, because an operation that never returns would outlive any
+        // grace period and the interval is over either way
+        if (this.firing !== undefined)
+            await Promise.race([this.firing, delay(DRAIN)]);
+    }
+    arm() {
+        const now = Date.now();
+        // a delay past this fires at once rather than late, so a long cycle is waited out in
+        // instalments; the wake-up finds the same interval and simply arms again
+        const wait = Math.min(this.boundary(now) - now, MAX_DELAY);
+        this.timer = setTimeout(() => this.tick(), wait);
+        this.timer.unref();
+    }
+    tick() {
+        if (this.closing)
+            return;
+        const ordinal = this.ordinal(Date.now());
+        // a timer may wake a millisecond before the boundary it was set for, and a cycle longer
+        // than one timer wakes several times on the way — both are the interval already handled
+        if (ordinal !== this.fired) {
+            this.fired = ordinal;
+            void this.fire(ordinal % this.n);
+        }
+        this.arm();
+    }
+    /**
+     * Nothing queues here. A call still running when the next boundary arrives means the work
+     * does not fit the gap, and starting a second one would only make that worse.
+     */
+    async fire(i) {
+        if (this.firing !== undefined) {
+            console.warn('Pulse skipped: the previous call has not returned', { pulse: this.label, interval: i });
+            return;
+        }
+        const owned = this.atom.slots(this.n);
+        if (owned === null) {
+            console.warn('Pulse skipped: this replica owns nothing', { pulse: this.label, interval: i });
+            return;
+        }
+        if (!owned.includes(i))
+            return;
+        /*
+         * A pulse calls and waits, so an operation that raised comes back as an exception here —
+         * the runtime carries it across and rethrows it in this process. What to do about one is a
+         * choice with no right answer, and asking would put the whole of it in front of anyone who
+         * only wanted an operation called every hour. So the interval is skipped: it is reported,
+         * and the next one is called as though it had not happened.
+         */
+        const firing = console.span(this.options, async () => await this.local.invoke(this.endpoint, { input: { n: this.n, i } }))
+            .catch((error) => {
+            console.error('Pulse failed', { pulse: this.label, interval: i, error });
+        })
+            .finally(() => { this.firing = undefined; });
+        this.firing = firing;
+        await firing;
+    }
+}
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms).unref());
+}
+/** `setTimeout` fires immediately past this, so a longer wait is taken in instalments */
+const MAX_DELAY = 2 ** 31 - 1;
+/** how long a call in flight is waited for on close */
+const DRAIN = 10_000;
+//# sourceMappingURL=Pulse.js.map

package/transpiled/Pulse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pulse.js","sourceRoot":"","sources":["../source/Pulse.ts"],"names":[],"mappings":"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"}

package/transpiled/const.d.ts

@@ -0,0 +1,15 @@
+/** The component the extension ships to hold delayed calls. */
+export declare const NAMESPACE = "cadence";
+export declare const COMPONENT = "metronome";
+/**
+ * Constant, never configuration: a row carries its lane, so lowering this would leave rows in
+ * lanes nobody reads any more. It is also the ceiling on replicas dispatching, and a power of
+ * two so that the common replica counts divide evenly. The outbox says the same of its own.
+ */
+export declare const LANES = 128;
+/** seconds between passes over the calls waiting to be made, and how far ahead each reaches */
+export declare const DISCRETENESS = 60;
+/** rows one scan brings back */
+export declare const BATCH = 200;
+/** A number from the environment, where a deployment or a test suite states one. */
+export declare function number(variable: string, fallback: number): number;

package/transpiled/const.js

@@ -0,0 +1,19 @@
+/** The component the extension ships to hold delayed calls. */
+export const NAMESPACE = 'cadence';
+export const COMPONENT = 'metronome';
+/**
+ * Constant, never configuration: a row carries its lane, so lowering this would leave rows in
+ * lanes nobody reads any more. It is also the ceiling on replicas dispatching, and a power of
+ * two so that the common replica counts divide evenly. The outbox says the same of its own.
+ */
+export const LANES = 128;
+/** seconds between passes over the calls waiting to be made, and how far ahead each reaches */
+export const DISCRETENESS = 60;
+/** rows one scan brings back */
+export const BATCH = 200;
+/** A number from the environment, where a deployment or a test suite states one. */
+export function number(variable, fallback) {
+    const value = Number(process.env[variable]);
+    return Number.isNaN(value) || value <= 0 ? fallback : value;
+}
+//# sourceMappingURL=const.js.map

package/transpiled/const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.js","sourceRoot":"","sources":["../source/const.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,SAAS,GAAG,SAAS,CAAA;AAClC,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAA;AAEpC;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,CAAA;AAExB,+FAA+F;AAC/F,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAA;AAE9B,gCAAgC;AAChC,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,CAAA;AAExB,oFAAoF;AACpF,MAAM,UAAU,MAAM,CAAE,QAAgB,EAAE,QAAgB;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;IAE3C,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAA;AAC7D,CAAC"}

package/transpiled/context.d.ts

@@ -0,0 +1,3 @@
+import type { Contribution } from '@toa.io/core';
+/** What this extension puts on the context of a component that declares it. */
+export declare function context(): Contribution;

package/transpiled/context.js

@@ -0,0 +1,9 @@
+/** What this extension puts on the context of a component that declares it. */
+export function context() {
+    return {
+        name: 'delay',
+        type: 'Delay',
+        imports: { '@toa.io/extensions.cadence': ['Delay'] }
+    };
+}
+//# sourceMappingURL=context.js.map

package/transpiled/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../source/context.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,MAAM,UAAU,OAAO;IACrB,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,EAAE,4BAA4B,EAAE,CAAC,OAAO,CAAC,EAAE;KACrD,CAAA;AACH,CAAC"}

package/transpiled/deployment.d.ts

@@ -0,0 +1,9 @@
+import type { Annotation } from './types.js';
+import type { Dependency } from '@toa.io/operations';
+/**
+ * The component that keeps delayed calls runs in a service of its own, the way the identity
+ * components run in the gateway. A composition may claim it and run it in its own pods instead.
+ */
+export declare function deployment(_: unknown, annotation?: Annotation | null): Dependency;
+/** The extension is deployed for the sake of `delay`, which nothing has to declare to use. */
+export declare const standalone = true;

package/transpiled/deployment.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { components } from './Composition.js';
+import { DISCRETENESS, NAMESPACE } from './const.js';
+import * as schemas from './schemas.js';
+/**
+ * The component that keeps delayed calls runs in a service of its own, the way the identity
+ * components run in the gateway. A composition may claim it and run it in its own pods instead.
+ */
+export function deployment(_, annotation) {
+    schemas.annotation.validate(annotation ?? null, 'Invalid cadence annotation');
+    // stated in seconds and carried in milliseconds, so that what an application writes is what
+    // the rest of a manifest is written in
+    const discreteness = (annotation?.discreteness ?? DISCRETENESS) * 1000;
+    const variables = [{ name: 'TOA_CADENCE_DISCRETENESS', value: String(discreteness) }];
+    const service = {
+        group: NAMESPACE,
+        name: 'metronome',
+        version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+        components: components().labels,
+        variables
+    };
+    return { services: [service] };
+}
+/** The extension is deployed for the sake of `delay`, which nothing has to declare to use. */
+export const standalone = true;
+//# sourceMappingURL=deployment.js.map

package/transpiled/deployment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.js","sourceRoot":"","sources":["../source/deployment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAIvC;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAE,CAAU,EAAE,UAA8B;IACpE,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAoB,UAAU,IAAI,IAAI,EAAE,4BAA4B,CAAC,CAAA;IAEhG,4FAA4F;IAC5F,uCAAuC;IACvC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,YAAY,IAAI,YAAY,CAAC,GAAG,IAAI,CAAA;IACtE,MAAM,SAAS,GACb,CAAC,EAAE,IAAI,EAAE,0BAA0B,EAAE,KAAK,EAAE,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IAErE,MAAM,OAAO,GAAY;QACvB,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO;QAC9F,UAAU,EAAE,UAAU,EAAE,CAAC,MAAM;QAC/B,SAAS;KACV,CAAA;IAED,OAAO,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAA;AAChC,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAA"}

package/transpiled/index.d.ts

@@ -0,0 +1,7 @@
+export { Factory } from './Factory.js';
+export { manifest } from './manifest.js';
+export { components } from './Composition.js';
+export { deployment, standalone } from './deployment.js';
+export { context } from './context.js';
+export { LANES } from './const.js';
+export type { Declaration, Delay, Pulse } from './types.js';

package/transpiled/index.js

@@ -0,0 +1,7 @@
+export { Factory } from './Factory.js';
+export { manifest } from './manifest.js';
+export { components } from './Composition.js';
+export { deployment, standalone } from './deployment.js';
+export { context } from './context.js';
+export { LANES } from './const.js';
+//# sourceMappingURL=index.js.map

package/transpiled/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/transpiled/manifest.d.ts

@@ -0,0 +1,11 @@
+import type { Declaration } from './types.js';
+import type { Manifest } from '@toa.io/norm';
+/**
+ * The `cadence:` block of a component manifest: the operations called on a cadence, by the
+ * operation each one calls. Norm hands over the whole manifest, so what the declaration refers
+ * to is checked here rather than left to fail at boot.
+ *
+ * A component that declares nothing still has a declaration. `cadence: ~` is how one that only
+ * delays calls says so, and it has to produce a value or norm rejects the extension.
+ */
+export declare function manifest(declaration: Declaration | null | undefined, component: Manifest): Declaration;

package/transpiled/manifest.js

@@ -0,0 +1,39 @@
+import * as schemas from './schemas.js';
+/**
+ * The `cadence:` block of a component manifest: the operations called on a cadence, by the
+ * operation each one calls. Norm hands over the whole manifest, so what the declaration refers
+ * to is checked here rather than left to fail at boot.
+ *
+ * A component that declares nothing still has a declaration. `cadence: ~` is how one that only
+ * delays calls says so, and it has to produce a value or norm rejects the extension.
+ */
+export function manifest(declaration, component) {
+    const normalized = expand(declaration);
+    // `intervals` is defaulted by the schema, so the declaration is only whole after this
+    schemas.declaration.validate(normalized, 'Invalid cadence declaration');
+    for (const [endpoint, pulse] of Object.entries(normalized)) {
+        const operation = component.operations?.[endpoint];
+        if (operation === undefined)
+            throw new Error(`Pulse refers to undefined operation '${endpoint}'`);
+        if (!TYPES.has(operation.type))
+            throw new Error(`Pulse '${endpoint}' must refer to an operation of the allowed types: ` +
+                [...TYPES].join(', '));
+        if (pulse.intervals > pulse.cycle)
+            throw new Error(`Pulse '${endpoint}' splits a cycle of ${pulse.cycle} seconds into ` +
+                `${pulse.intervals} intervals, which is less than a second each`);
+    }
+    return normalized;
+}
+/** A pulse whose cycle is not split has nothing to state but the cycle. */
+function expand(declaration) {
+    if (declaration === null || declaration === undefined)
+        return {};
+    return Object.fromEntries(Object.entries(declaration)
+        .map(([endpoint, pulse]) => [endpoint, typeof pulse === 'number' ? { cycle: pulse } : pulse]));
+}
+/**
+ * The types a receiver may refer to. An operation that produces no side effects has nothing to
+ * be called periodically for.
+ */
+const TYPES = new Set(['transition', 'assignment', 'effect', 'unmanaged']);
+//# sourceMappingURL=manifest.js.map

package/transpiled/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAIvC;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAE,WAA2C,EACnE,SAAmB;IACnB,MAAM,UAAU,GAA4B,MAAM,CAAC,WAAW,CAAC,CAAA;IAE/D,sFAAsF;IACtF,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAc,UAAU,EAAE,6BAA6B,CAAC,CAAA;IAEpF,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,MAAM,SAAS,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,CAAA;QAElD,IAAI,SAAS,KAAK,SAAS;YACzB,MAAM,IAAI,KAAK,CAAC,wCAAwC,QAAQ,GAAG,CAAC,CAAA;QAEtE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,qDAAqD;gBACrF,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QAE1B,IAAI,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,KAAK;YAC/B,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,uBAAuB,KAAK,CAAC,KAAK,gBAAgB;gBAClF,GAAG,KAAK,CAAC,SAAS,8CAA8C,CAAC,CAAA;IACvE,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,2EAA2E;AAC3E,SAAS,MAAM,CAAE,WAA2C;IAC1D,IAAI,WAAW,KAAK,IAAI,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IAEhE,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SAClD,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,CACzB,CAAC,QAAQ,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAA"}

package/transpiled/schemas.d.ts

@@ -0,0 +1,4 @@
+import type { Schema } from '@toa.io/schemas';
+import type { Annotation, Declaration } from './types.js';
+export declare const declaration: Schema<Declaration>;
+export declare const annotation: Schema<Annotation>;

package/transpiled/schemas.js

@@ -0,0 +1,7 @@
+import { resolve } from 'node:path';
+import * as schemas from '@toa.io/schemas';
+const path = resolve(import.meta.dirname, '../schemas');
+const namespace = schemas.namespace(path);
+export const declaration = namespace.schema('declaration');
+export const annotation = namespace.schema('annotation');
+//# sourceMappingURL=schemas.js.map

package/transpiled/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../source/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAA;AAI1C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;AACvD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AAEzC,MAAM,CAAC,MAAM,WAAW,GAAwB,SAAS,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAuB,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA"}

package/transpiled/types.d.ts

@@ -0,0 +1,34 @@
+/** What one component declares under `cadence:`, by the operation each one calls. */
+export type Declaration = Record<string, Pulse>;
+export interface Pulse {
+    /** seconds one whole cycle takes */
+    cycle: number;
+    /** intervals the cycle is split into; the gap between calls is `cycle / intervals` */
+    intervals: number;
+}
+/** `context.delay` — a call to be made later, answering the id that cancels it. */
+export interface Delay {
+    (endpoint: string, request: object | null, options: Options): Promise<string>;
+    /** Raises where the id was never issued. */
+    cancel: (id: string) => Promise<void>;
+}
+export interface Options {
+    /** milliseconds from now */
+    interval: number;
+    /**
+     * Milliseconds the call may be late and still be made, or `null` for no bound at all.
+     *
+     * Stated rather than defaulted, because only the caller knows whether a late call is still
+     * the right call: an unpaid order expires on time or not at all, and a report is wanted
+     * whenever it can be had. Nothing else in the system can tell those apart.
+     *
+     * An upper bound on lateness, not a promise of timeliness. It is bounded below by how often
+     * a dispatcher scans, so a bound shorter than that is one nothing can honour.
+     */
+    overdue: number | null;
+}
+/** What an application states under `cadence:` in its context. */
+export interface Annotation {
+    /** seconds between passes over the calls waiting to be made */
+    discreteness?: number;
+}

package/transpiled/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/transpiled/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":""}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./transpiled",
+    "rootDir": "./source"
+  },
+  "include": [
+    "source"
+  ],
+  "exclude": [
+    "**/*.test.ts"
+  ]
+}