@fougere/core 0.1.0-alpha.0

package/dist/seed.js

@@ -0,0 +1,110 @@
+/**
+ * Seeds in dependency order — a `ref()` target is planted before its referrer.
+ *
+ * The order is a fact about the entity graph, not about the surface running the seeds,
+ * so it is stated once here. The Nuxt module read it off a pairwise comparator (which
+ * `Array.sort` cannot make transitive: `a` before `b` and `b` before `c` never implies
+ * `a` before `c`), and `boot()` had no order at all — the same fact, told twice and
+ * wrong both times. A list seeded before its owner failed on the foreign key, and the
+ * driver's error named neither the entity nor the file.
+ *
+ * Kahn, like `orderTables` in `@fougere/schema-sql` — the same shape one level up: there
+ * the nodes are tables and the edges FK columns, here they are seeds and the edges the
+ * `one` relations of the entities they target. A cycle cannot be satisfied by ordering,
+ * so its remaining seeds keep their scan order and land last: the driver refuses what is
+ * genuinely impossible, and everything acyclic around it still gets planted.
+ */
+export function orderSeeds(fronds) {
+    const refs = new Map();
+    for (const frond of fronds) {
+        for (const entity of frond.entities) {
+            const targets = new Set();
+            for (const field of Object.values(entity.entityClass.getFields())) {
+                if (field.role?.relation?.kind !== 'one')
+                    continue;
+                const target = field.role.relation.to().name?.toLowerCase();
+                if (target && target !== entity.name.toLowerCase())
+                    targets.add(target);
+            }
+            refs.set(entity.name.toLowerCase(), targets);
+        }
+    }
+    const seeds = fronds.flatMap((frond) => frond.seeds);
+    const seeded = new Set(seeds.map((seed) => seed.entityName.toLowerCase()));
+    // Only what is actually seeded can be waited for: a relation to an entity with no seed
+    // is already satisfied by whatever put its rows there.
+    const waiting = new Map(seeds.map((seed) => {
+        const own = seed.entityName.toLowerCase();
+        const targets = [...(refs.get(own) ?? [])].filter((target) => seeded.has(target) && target !== own);
+        return [seed, new Set(targets)];
+    }));
+    const ordered = [];
+    const planted = new Set();
+    while (waiting.size > 0) {
+        const ready = [...waiting.keys()].find((seed) => [...waiting.get(seed)].every((dep) => planted.has(dep)));
+        if (!ready)
+            break;
+        ordered.push(ready);
+        planted.add(ready.entityName.toLowerCase());
+        waiting.delete(ready);
+    }
+    return [...ordered, ...waiting.keys()];
+}
+/**
+ * Plant a set of seeds, in the order given. Reports what it did, one line per entity.
+ *
+ * The one seeding loop. `boot()` had one and the Nuxt module generated a second into its
+ * Nitro plugin, which had drifted: no ORM fallback, so an entity with no façade was
+ * skipped there and planted here. Two answers to "how does a row get in at boot" is one
+ * too many, and the second was the one running in the browser.
+ */
+export async function runSeeds(app, seeds, report = () => { }) {
+    for (const seed of seeds) {
+        const resolve = (name) => app.resolve(name + 'Handler');
+        const data = typeof seed.data === 'function' ? await seed.data(resolve) : seed.data;
+        const door = doorFor(app, seed.entityName);
+        if (!door) {
+            report(`  ${seed.entityName}: no handler façade nor ORM — skipping seed`);
+            continue;
+        }
+        const existing = await door.list();
+        if (existing.length > 0) {
+            report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
+            continue;
+        }
+        // The driver's error alone names neither the entity nor the row — and a foreign
+        // key is exactly what a seed gets wrong.
+        for (const item of data) {
+            try {
+                await door.write(item);
+            }
+            catch (cause) {
+                throw new Error(`Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${cause?.message ?? cause}`, { cause });
+            }
+        }
+        report(`  ${seed.entityName}: ${data.length} records`);
+    }
+}
+/**
+ * A seed is not a client: it writes at boot, from inside. The façade is used when the
+ * entity declares one (its judge catches a bad seed early), the storage when it does
+ * not — an entity that exposes nothing is still an entity whose reference rows must land.
+ */
+function doorFor(app, entityName) {
+    let handler;
+    try {
+        handler = app.resolve(`${entityName}Handler`);
+    }
+    catch { }
+    if (typeof handler?.list === 'function' && typeof handler.create === 'function') {
+        return {
+            list: () => handler.list(),
+            write: (item) => handler.create({ params: {}, query: {}, body: item, state: {} }),
+        };
+    }
+    const orm = app.ormFor(entityName);
+    if (!orm)
+        return undefined;
+    return { list: () => orm.list(), write: (item) => orm.create(item) };
+}
+//# sourceMappingURL=seed.js.map

package/dist/seed.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,387 @@
+import type { Container } from '@fougere/container';
+import type { ParsedParam } from './operation.js';
+import type { EntityOrm, OrmFactory } from './orm.js';
+import type { SchemaLike } from '@fougere/schema';
+import type { OperationContract, OperationsMap } from './operation.js';
+import type { AppMiddleware } from './middleware.js';
+import type { PresenterViews } from './presenter.js';
+import type { Transport } from './call.js';
+/**
+ * A discovered provider — a class under `services/` or `repositories/`, injected by type.
+ *
+ * Which of the two directories it came from is deliberately not recorded. The scan used
+ * to tag it `kind: 'service' | 'repository'`, a field it filled on every provider and
+ * that **no consumer ever read** — the two directories are two spellings of the same
+ * thing, and DI resolves by type either way.
+ */
+export interface ProviderEntry {
+    /** Registration key: class name with first letter lowercased. */
+    name: string;
+    /** The class constructor (default export of the file). */
+    ctor: new (...args: unknown[]) => unknown;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** A discovered entity (Entity subclass in entities/ dir). */
+export interface EntityEntry {
+    /** Registration key: class name lowercased first char (e.g. 'product'). */
+    name: string;
+    /** The Entity class (has static getFields()). */
+    entityClass: SchemaLike;
+    /** Absolute file path (for debugging). */
+    filePath: string;
+    /** Whether this entity is part of the frond's public contract. */
+    exposed?: boolean;
+}
+/** A discovered handler (controls what a service exposes). */
+export interface HandlerEntry {
+    /** Registration key (e.g. 'postHandler'). */
+    name: string;
+    /**
+     * The name this handler answers to — its class name minus `Handler`, lowercased
+     * (`PostHandler` → `post`). It is what `facadeKeyOf` builds its key from and what
+     * travels as `FrondCall.entity` on the wire.
+     *
+     * **It is NOT an entity name**, and it was called `entityName` for long enough to
+     * mislead: `toEntityName` (`scanner.ts`) strips the suffix without checking that any
+     * entity carries the result, and the boot states the consequence — *pointing at
+     * nothing is legal*. A health check, a search across several shapes, a pure
+     * computation: ordinary handlers that own no row. `PresenterEntry`/`CollectorEntry`
+     * keep `entityName` because those really do target a declared entity.
+     */
+    address: string;
+    /** The handler class. */
+    ctor: new (...args: unknown[]) => unknown;
+    /** All operations with full signatures for binding. */
+    operations: OperationsMap;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+    /** Whether this handler is part of the frond's public contract. */
+    exposed?: boolean;
+    /** Output schema override — when Crud(Entity, Output), restricts ORM output. */
+    outputOverride?: SchemaLike;
+    /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
+    surface?: string;
+}
+/** Return type metadata for a presenter computed field. */
+export interface PresenterFieldMeta {
+    name: string;
+    /** Inferred return type name: 'string', 'number', 'boolean', or a class name. */
+    returnType?: string;
+    /**
+     * The field emits a LIST per row — `tags(posts: Post[]): string[][]`.
+     *
+     * The method answers one value per row, so the outer array level of its return type is
+     * the page, not the field: what remains after removing it is the field's own arity.
+     * Nothing measured that remainder, so a computed list and a computed scalar looked
+     * identical and every projection announced the scalar.
+     */
+    list?: boolean;
+    /** Whether the return is nullable. */
+    nullable?: boolean;
+    /**
+     * The declared parameters AFTER the rows. Kept raw rather than resolved: the scan
+     * meets presenters before collectors, so the plan is computed at boot where the
+     * collector names are known — exactly as a handler op's is.
+     *
+     * A computed field that declares `user: User | null` is then fed by the collector
+     * that resolves one. A presenter is not a second mechanism.
+     */
+    params?: ParsedParam[];
+}
+/** A discovered presenter (computed fields for an entity's output). */
+export interface PresenterEntry {
+    /** Entity name this presenter enriches (e.g. 'post' from PostPresenter). */
+    entityName: string;
+    /** The presenter class. */
+    ctor: new (...args: unknown[]) => unknown;
+    /** Computed field names (method names on prototype). */
+    fields: string[];
+    /** Per-field type metadata (inferred from source via parser). */
+    fieldMeta: PresenterFieldMeta[];
+    /**
+     * The view each computed field emits, when the presenter declares one
+     * (`Presenter(Order, { items: [OrderItemView] })`). Stated rather than inferred: the
+     * parser reads a scalar off a return type and nothing more, so an object-valued field
+     * has no derivable shape without this.
+     */
+    views?: PresenterViews;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** A discovered collector (resolves handler input params from invocation context). */
+export interface CollectorEntry {
+    /** Entity name this collector resolves (e.g. 'user' from UserCollector). */
+    entityName: string;
+    /** The collector class. */
+    ctor: new (...args: unknown[]) => unknown;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** A discovered seed file (array of records or async factory). */
+export interface SeedEntry {
+    /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
+    entityName: string;
+    /** Raw default export — array or function. Resolved at runtime. */
+    data: Record<string, unknown>[] | SeedFactory;
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** Seed factory — receives a resolver to access handlers cross-frond. */
+export type SeedFactory = (resolve: <T>(name: string) => T) => Promise<Record<string, unknown>[]>;
+/** Where a frond lives on disk. */
+export interface FrondSource {
+    /** Absolute path to the frond directory. */
+    path: string;
+    /** The @frond/{name} package name. Always present. */
+    package: string;
+}
+export interface FrondDescriptor {
+    name: string;
+    source: FrondSource;
+    providers: ProviderEntry[];
+    entities: EntityEntry[];
+    handlers: HandlerEntry[];
+    presenters: PresenterEntry[];
+    collectors: CollectorEntry[];
+    seeds: SeedEntry[];
+    /** Per-surface entity lists from frond.config.ts (e.g. { graphql: ['Post'], rest: ['Post', 'Author'] }). */
+    surfaces?: Record<string, string[]>;
+    /**
+     * Per-operation overrides from frond.config.ts. Key = operation name.
+     *
+     * Two depths, as declared on {@link OperationOverride}: the surface keys travel to the
+     * transport adapters, the contract keys (`input`/`output`/`binding`) travel to the
+     * façade — where config is the third producer of an operation's contract, alongside a
+     * prefab's `__ops` and the scan.
+     */
+    operationsOverrides?: Record<string, OperationContract & {
+        kind?: 'query' | 'command';
+        /** Class name to resolve from DI (overrides default `{Entity}Handler` lookup). */
+        handlerName?: string;
+        /** Method name on the resolved handler (defaults to op name). */
+        method?: string;
+        /** CASL ability string for opt-in policy check. */
+        policy?: string;
+    }>;
+}
+/** Result of scanning a project directory. */
+/**
+ * Something the scan could NOT do — recorded instead of swallowed.
+ *
+ * The scan answers with what it found. Until now it answered the same way whether
+ * a directory held nothing or could not be read, and whether a handler declared no
+ * operation or failed to parse: `catch → empty`. So every downstream reader — the
+ * façade, the identity card, anything asking "what does this app serve?" — could
+ * not tell **"there is nothing"** from **"I could not look"**.
+ *
+ * That distinction is what makes a rule about an ABSENCE sound. Without it, a check
+ * derived from the scan reports "nothing wrong" precisely when it read nothing.
+ */
+export interface ScanDiagnostic {
+    /**
+     * `blocking` — the app now serves less than its source declares, and no caller
+     * can know it: a handler that failed to parse contributes zero operations.
+     * `warning` — something may be missing and the scan cannot decide, e.g. a base
+     * class it is not allowed to resolve. Statable in `frond.config.ts`.
+     */
+    severity: 'blocking' | 'warning';
+    /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */
+    code: string;
+    /** Absolute path of what could not be read. */
+    filePath: string;
+    /** The frond it belongs to, when the scan got far enough to know. */
+    frond?: string;
+    /** What could not be done, and what it costs. One sentence, for a human. */
+    message: string;
+    /** The underlying failure, kept whole. */
+    cause?: unknown;
+}
+export interface ScanResult {
+    fronds: FrondDescriptor[];
+    /** What the scan could not do. Empty is a claim, not a default — see {@link ScanDiagnostic}. */
+    diagnostics: ScanDiagnostic[];
+}
+/**
+ * Lazy auth declaration written in fougere.config.ts.
+ *
+ * Each @fougere/auth-* package exports a factory (e.g. `betterAuth(opts)`) that
+ * returns this shape. The `create()` method is called once at boot with the
+ * resolved db + ormFactory, so the provider can wire its engine through Fougere.
+ */
+export interface AuthConfig {
+    /** Build the runtime — invoked by createApp at boot with the resolved storage handles. */
+    create(ctx: AuthContext): AuthRuntime | Promise<AuthRuntime>;
+    /**
+     * Entities the provider will use. Optional metadata — useful for the core's
+     * future migration registry to know which tables auth needs.
+     */
+    entities?: Record<string, SchemaLike>;
+}
+/**
+ * Context passed by the core to an auth provider's create() function.
+ * Provides the resources the provider needs to integrate with the app.
+ */
+export interface AuthContext {
+    /** Storage handle (Kysely DB instance, Prisma client, etc.) — opaque to core. */
+    db: unknown;
+    /** Per-entity ORM factory — auth provider uses this to back its adapter. */
+    ormFactory: OrmFactory;
+}
+/**
+ * Runtime returned by an auth provider's create(config, ctx) function.
+ * The core mounts this on the App and the HTTP layer (Nuxt module / router) uses it.
+ */
+export interface AuthRuntime {
+    /** Entities used by the provider, including any defaults it filled in. */
+    entities: Record<string, SchemaLike>;
+    /**
+     * Per-entity ORMs the provider built for itself. Exposed so app code can
+     * query auth tables (e.g. list active sessions for a user) without rebuilding
+     * the same EntityOrm.
+     */
+    orms: Record<string, EntityOrm>;
+    /** Web Standard handler that processes /auth/* requests. */
+    handler: (request: Request) => Promise<Response>;
+    /** Programmatic API exposed by the provider (getSession, signOut, ...). */
+    api: Record<string, unknown>;
+    /** Effective mount path (echoes config.basePath or the provider's default). */
+    basePath: string;
+}
+/** Options for createApp(). */
+export interface CreateAppOptions {
+    /** Project root directory. Defaults to process.cwd(). */
+    root?: string;
+    /** Factory function to create the container. Required. */
+    createContainer: () => Container;
+    /** Factory to auto-generate EntityOrm for each scanned entity. */
+    ormFactory?: OrmFactory;
+    /** Only load these fronds (by name). If absent, load all. */
+    fronds?: string[];
+    /**
+     * Remote fronds — label → address. What each remote hosts is discovered
+     * at the first miss (rpc.discover), never declared here.
+     */
+    remotes?: Record<string, string>;
+    /**
+     * Builds the transport used to reach `remotes` addresses. Wired by
+     * layer-2 packages (e.g. @fougere/transport-http); required when
+     * `remotes` is non-empty.
+     */
+    remoteTransport?: (url: string) => Transport;
+    /**
+     * Carries an announced fact out of this process — a broker, a queue, a log.
+     *
+     * Called for every emission, ALONGSIDE the local dispatch and never instead of it: a
+     * listener in this process is reached directly, and this is how the others hear.
+     *
+     * It exists because the local dispatch finds its listeners by having READ their code,
+     * which stops at the repository boundary. A carrier hands the fact to a NAME; the far
+     * side subscribes to that same name from its own code, and neither ever reads the other.
+     *
+     * Its failure never reaches the emitter — same rule as a subscriber's.
+     */
+    onEmit?: (fact: string, payload: unknown) => void | Promise<void>;
+    /**
+     * Storage handle to expose to the auth provider via AuthContext.db.
+     * Required when `auth` is set.
+     */
+    db?: unknown;
+    /** Auth declaration to wire into the app at boot. */
+    auth?: AuthConfig;
+}
+/** The App object returned by createApp(). */
+export interface App {
+    /** Root container with builtins + frond scopes. */
+    container: Container;
+    /** Discovered fronds metadata. */
+    fronds: FrondDescriptor[];
+    /** Resolve from root container (shortcut). */
+    resolve<T>(name: string): T;
+    /**
+     * Resolve an entity's schema — the local `entityClass` when it's hosted or
+     * scanned here, else reconstructed from the remote's identity card
+     * (rpc.discover → reconstruct()). The one way to get a live schema for an
+     * entity whose class may not be importable at all (another repo, another
+     * language) — a card travelled, but until now its `schema` was thrown away.
+     */
+    schemaFor(entity: string): Promise<SchemaLike>;
+    /**
+     * The door a name exposes to one audience, or `undefined` when it exposes
+     * none. A named surface is CLOSED: a name with no door of its own under that
+     * surface is not in it — it never falls back to the full one.
+     *
+     * **Not always a façade**, despite the name: when the owning frond is declared
+     * remote, nothing is registered locally (`bootstrap.ts`, `declaredRemotes`) and
+     * this resolves to a doublure — a façade-shaped stand-in (`remote.ts`). The
+     * caller cannot tell, which is the point; the word here was simply wrong.
+     *
+     * The one way an adapter reaches that door. It exists so the key format stays
+     * inside core (see `facadeKeyOf`), which is what lets a projection package
+     * stay structurally typed and depend on nothing.
+     */
+    facadeFor(entity: string, surface?: string): Record<string, Function> | undefined;
+    /**
+     * The facts this app has a listener for — what a carrier must subscribe to on its behalf.
+     *
+     * Derived from the signatures it scanned (`Fact<T>` in an op's parameters), so a process
+     * states what it listens to without anyone declaring it twice. The dual of `onEmit`: one
+     * says what leaves, this says what should be brought in.
+     */
+    listensTo(): string[];
+    /**
+     * Hand a fact that came from OUTSIDE to the listeners in this process — and stop there.
+     *
+     * The dual of `onEmit`, and deliberately not the same thing as announcing: resolving the
+     * emission value to deliver an inbound fact would carry it straight back out through
+     * `onEmit`, so a hub echoed every reading it received to the whole fleet. Receiving and
+     * announcing are two operations; only one of them leaves.
+     *
+     * The local dispatch is identical either way — same judge, same binding, same
+     * middlewares — so a fact off a wire is no less checked than one raised next door.
+     *
+     * **It waits, and it tells** — the opposite of announcing, on purpose. It resolves once
+     * every listener here is done, and REJECTS with an `AggregateError` if any refused. A
+     * carrier's whole job is to know whether the fact landed: at-least-once is retrying what
+     * failed, so a delivery that cannot report makes durability impossible to build above it.
+     * "Dispatch is not delivery" protects the EMITTER from a slow subscriber; a carrier is
+     * not the emitter, it is the party whose business this is.
+     *
+     * It still holds nothing. A refused fact is refused, and whether it comes back is the
+     * carrier's decision — Fougere puts the channel underneath rather than reimplementing it.
+     */
+    deliver(fact: string, payload: unknown): Promise<void>;
+    /**
+     * The storage an entity is backed by, resolved through its owning frond's scope —
+     * the dual of {@link facadeFor}. `undefined` when no loaded frond hosts the entity,
+     * or when the app booted with no storage at all.
+     *
+     * `unknown` because the port belongs to whoever wired it: narrowing it to `EntityOrm`
+     * is the caller saying which implementation they are standing on.
+     */
+    ormFor(entity: string): unknown | undefined;
+    /** Dispose the root container. */
+    dispose(): Promise<void>;
+    /**
+     * The same disposal, spelled so the language does it: `await using app = await
+     * createApp(…)`. Twelve of the twenty-six mounts in this repo's own tests never
+     * called `dispose()` — a scope that closes itself is the only version of that
+     * rule nobody forgets.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Register a global app middleware (runs on every operation). */
+    use(middleware: AppMiddleware): void;
+    /** Register an app middleware scoped to a specific entity. */
+    use(entity: string, middleware: AppMiddleware): void;
+    /** Auth runtime, present when fougere.config.ts declares `auth`. */
+    auth?: AuthRuntime;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/verify.d.ts

@@ -0,0 +1,57 @@
+import type { App } from './types.js';
+/**
+ * What a rule found in an app.
+ *
+ * `message` is the sentence the rule replaces — the prose a human used to have
+ * to remember. `Known issues` says "Keep collectors in the consuming frond";
+ * this is that sentence, told about a specific handler, by something that runs.
+ */
+export interface Violation {
+    /** Rule name, stable — 'cross-frond-dependency'. */
+    rule: string;
+    /** The frond the subject lives in. */
+    frond: string;
+    /** What violates it — 'PostHandler'. */
+    subject: string;
+    /** Where to go and look. */
+    filePath: string;
+    /**
+     * What the subject reaches for, and where it actually lives.
+     *
+     * `frond` above is the CONSUMER; the target used to exist only inside the
+     * sentence. A reader that has to parse prose to learn which frond a violation
+     * points at is a second opinion on a fact the checker already held — so the
+     * boot can ask "does this violation target a frond named in `remotes:`?" by
+     * reading a field.
+     */
+    dependsOn: {
+        key: string;
+        frond: string;
+        kind: string;
+    };
+    /** What breaks, and what the caller gets instead. */
+    message: string;
+}
+/**
+ * Does this app survive being split?
+ *
+ * A frond runs in-process or in its own process behind JSON-RPC with identical
+ * user code — that is the whole claim. What the claim does not say is that
+ * *every* app survives the move: a dependency that crosses a frond boundary
+ * resolves today because both scopes live in one container, and resolves to
+ * nothing the day the other frond answers over the wire.
+ *
+ * The gradient is the one question no other framework can ask. Nest has nothing
+ * to check — every inter-module call is already remote, so nothing changes when
+ * you split. Spring Modulith has nothing to check either — it plans no exit.
+ * Here the question means something, and until now it had no answer.
+ *
+ * Pure over `app.fronds`: no mount, no process, no file. Call it from a test.
+ */
+export declare function verify(app: Pick<App, 'fronds'>): Violation[];
+/**
+ * The same verdict, as an assertion. Throws naming every rule that failed, so a
+ * test is one line and its output is the sentence — not a diff of two objects.
+ */
+export declare function assertSplittable(app: Pick<App, 'fronds'>): void;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAmB,MAAM,YAAY,CAAC;AAMvD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAwCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,SAAS,EAAE,CA+E5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,IAAI,CAK/D"}