litedbmodel 2.1.0 → 2.2.0

package/dist/scp/decorator-adapter.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — the decorator METADATA adapter (Phase F-1, epic #74, issue #104).
+ *
+ * litedbmodel's decorators are metadata-only COLLECTORS: `@column` / `@hasMany` / … record
+ * `ColumnMeta` / `RelationMeta` / `TABLE_NAME` on the class (`src/decorators.ts`, via `reflect-metadata`
+ * + `_columnMeta` / `_relationMeta`). This module READS that registry and translates it into the SCP-level
+ * facts the rest of the stack consumes, plus the write bundles a decorated model compiles to. It builds
+ * NO SQL structure of its own and holds NO authoring vocabulary — the decorator never emits IR, and the
+ * adapter never re-implements composition.
+ *
+ * ## What the adapter translates
+ *
+ *  1. **Columns** (the one real translation): `@column.*` `ColumnMeta` (the decorator already knows the
+ *     type family — bigint / date / boolean / uuid / json / array / …) → the SCP column SoT
+ *     ({@link ModelColumns}: the SQL-type token per column, validated by `coltype.ts`). See
+ *     {@link deriveModelColumns} + {@link COLUMN_FAMILY_SQL_TYPE}. The typed-read `outType` and the
+ *     relation key-array element type both resolve against exactly this SoT.
+ *  2. **Relations**: `@hasMany` / `@belongsTo` / `@hasOne` `RelationMeta` → {@link RelationDecl} →
+ *     `compileRelationOp` (single + composite keys, per-parent `limit` window + `hardLimit`).
+ *  3. **Write bundles**: `createMany` (and a `create` WITH `onConflict`) / `updateMany` / `deleteMany` →
+ *     `compileCreateManyBundle` / `compileUpdateManyBundle` / `compileDeleteManyBundle`, with the
+ *     model's column SoT threaded as the write de-box resolver.
+ *
+ * READS are NOT compiled here. A read endpoint is DECLARED on the `@behavior` / `@leaf` authoring
+ * surface and lowered by `bc generate`; an ad-hoc runtime-shaped query runs the v1 imperative path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_UNCAST_SQL_TYPE = exports.COLUMN_FAMILY_SQL_TYPE = void 0;
+exports.columnSqlType = columnSqlType;
+exports.deriveModelColumns = deriveModelColumns;
+exports.tableNameOf = tableNameOf;
+exports.compileCreateBundle = compileCreateBundle;
+exports.compileUpdateBundle = compileUpdateBundle;
+exports.compileDeleteBundle = compileDeleteBundle;
+exports.relationKeyTypeResolver = relationKeyTypeResolver;
+exports.modelColumnResolver = modelColumnResolver;
+exports.deriveRelationDecls = deriveRelationDecls;
+exports.relationDeclOf = relationDeclOf;
+exports.compileRelationOps = compileRelationOps;
+const write_bundle_1 = require("./write-bundle");
+const relation_1 = require("./relation");
+const coltype_1 = require("./coltype");
+const decorators_1 = require("../decorators");
+const Column_1 = require("../Column");
+// ── 1. Column-type mapping (decorator ColumnMeta → the SCP column SQL type) ─────────────────────
+/**
+ * The decorator's `ColumnMeta.sqlCast` type-family token → the canonical §4.1 SQL-type token the SCP
+ * `static columns` SoT carries (validated by `coltype.ts`). The decorator ALREADY knows the family
+ * (it set `sqlCast` from the `@column.*` variant / the `design:type` inference — `src/decorators.ts`),
+ * so this is a pure token normalization, no inference. `coltype.ts` accepts every RHS here:
+ * BOOLEAN/BIGINT/TIMESTAMP/DATE/UUID/JSONB are scalar; the array tokens de-box as `passthrough`
+ * (`sqlTypeToMaterializeClass`).
+ *
+ * The RHS matches the decorator families 1:1:
+ *  - `boolean`    → `BOOLEAN`     (`@column.boolean()` / auto `Boolean`)
+ *  - `bigint`     → `BIGINT`      (`@column.bigint()` / auto `BigInt` — read de-box: exact string)
+ *  - `timestamp`  → `TIMESTAMP`   (`@column.datetime()` / auto `Date` — read de-box: TZ string)
+ *  - `date`       → `DATE`        (`@column.date()` — read de-box: YYYY-MM-DD string)
+ *  - `uuid`       → `UUID`        (`@column.uuid()`)
+ *  - `jsonb`      → `JSONB`       (`@column.json()`)
+ *  - `text[]` / `int[]` / `numeric[]` / `boolean[]` → the array token (`@column.*Array()`)
+ */
+exports.COLUMN_FAMILY_SQL_TYPE = {
+    boolean: 'BOOLEAN',
+    bigint: 'BIGINT',
+    timestamp: 'TIMESTAMP',
+    date: 'DATE',
+    uuid: 'UUID',
+    jsonb: 'JSONB',
+    'text[]': 'TEXT[]',
+    'int[]': 'INT[]',
+    'numeric[]': 'NUMERIC[]',
+    'boolean[]': 'BOOLEAN[]',
+};
+/**
+ * The LAST-RESORT SQL type for a column that carries NO `sqlCast` family, NO `baseSqlType` (its
+ * `design:type` is absent — no `emitDecoratorMetadata` — or is an Array/Object family), and NO
+ * `columnTypes` override. Phase F-2 (#105 option B) made {@link columnSqlType} consult the decorator's
+ * `baseSqlType` (derived from the field's TS `design:type`: String→TEXT / Number→INTEGER / Boolean→
+ * BOOLEAN / Date→TIMESTAMP / BigInt→BIGINT) BEFORE this default, so a bare `@column() name: string`
+ * types as `TEXT` (not `INTEGER`) — the fix for F1's blanket-INTEGER read-de-box defect (it threw
+ * `materialize int32` on a live string column). This default now only applies when `design:type` is
+ * genuinely unavailable; a REAL/DECIMAL column (a `Number` that is not INT) is pinned via
+ * {@link DeriveColumnsOptions.columnTypes} (the escape hatch, unchanged from F1).
+ */
+exports.DEFAULT_UNCAST_SQL_TYPE = 'INTEGER';
+/**
+ * Translate ONE column's {@link ColumnMeta} to its §4.1 SQL-type token. Precedence (Phase F-2 / #105
+ * option B):
+ *   1. an explicit `columnTypes` override (the REAL/DECIMAL/width escape hatch) wins;
+ *   2. else the family token from {@link COLUMN_FAMILY_SQL_TYPE} (an explicit `@column.*` `sqlCast`);
+ *   3. else the decorator's `baseSqlType` — derived from the field's TS `design:type` (String→TEXT /
+ *      Number→INTEGER / Boolean→BOOLEAN / Date→TIMESTAMP / BigInt→BIGINT), so a bare `@column()` types
+ *      correctly for the SCP typed-read de-box (the fix for F1's blanket-INTEGER default);
+ *   4. else {@link DEFAULT_UNCAST_SQL_TYPE} (only when `design:type` is unavailable).
+ * Fail-closed: a family token the mapping does not know, or a produced token `coltype.ts` rejects,
+ * THROWS (naming the column) — never a silent skip (no-assume, no-fallback).
+ */
+function columnSqlType(propKey, meta, override) {
+    const sqlType = override ??
+        (meta.sqlCast !== undefined ? exports.COLUMN_FAMILY_SQL_TYPE[meta.sqlCast] : undefined) ??
+        meta.baseSqlType ??
+        exports.DEFAULT_UNCAST_SQL_TYPE;
+    if (meta.sqlCast !== undefined && override === undefined && exports.COLUMN_FAMILY_SQL_TYPE[meta.sqlCast] === undefined) {
+        throw new Error(`decorator-adapter: column '${propKey}' has decorator sqlCast family '${meta.sqlCast}' with no ` +
+            `SCP SQL-type mapping. Add it to COLUMN_FAMILY_SQL_TYPE or pin the column via ` +
+            `options.columnTypes['${propKey}']. No-assume, no-fallback.`);
+    }
+    // Validate the produced token is in the §4.1 vocabulary (throws for an unknown/ambiguous type).
+    (0, coltype_1.sqlTypeToMaterializeClass)(sqlType);
+    return sqlType;
+}
+/**
+ * Derive the SCP `static columns` ({@link ModelColumns}) for a decorated model class from its
+ * `@column` `ColumnMeta` registry (the decorator IS the type SoT for v1/v2's decorator surface). The
+ * table is the model's `TABLE_NAME` (or the model-name lowercased, matching the decorator's
+ * `effectiveTableName`). Each column keys by its DB `columnName` (what a SELECT projects), mapping to
+ * its §4.1 SQL type. A model with no `@column` declarations yields no table entry.
+ *
+ * This is the ONE real translation in the adapter — the read-path de-box (INT→number / BIGINT→string /
+ * DATE→string / BOOLEAN→boolean) and the codegen `outType` both consult exactly this SoT.
+ */
+function deriveModelColumns(modelClass, options = {}) {
+    const meta = (0, decorators_1.getColumnMeta)(modelClass);
+    if (meta === undefined || meta.size === 0)
+        return {};
+    const table = tableNameOf(modelClass);
+    const cols = {};
+    for (const [propKey, m] of meta) {
+        cols[m.columnName] = columnSqlType(propKey, m, options.columnTypes?.[propKey]);
+    }
+    return { [table]: cols };
+}
+/** The effective table name (v1 `@model` rule): explicit `TABLE_NAME`, else the model name lowercased. */
+function tableNameOf(modelClass) {
+    return modelClass.TABLE_NAME ?? modelClass.name.toLowerCase();
+}
+// ── 2. Write bundles (createMany / updateMany / deleteMany) ─────────────────────────────────────
+/**
+ * Compile a decorated model's `createMany` — and a `create` WITH `onConflict` (upsert) — into a batch
+ * write {@link SqlBundle} via `compileCreateManyBundle`. This is the UPSERT carry: `onConflict` /
+ * `onConflictUpdate` / `onConflictIgnore` are `compileInsertMany` BUILD options (not authored ports),
+ * so they carry end-to-end here with NO SCP authoring addition — exactly as v1's `create` and
+ * `createMany` share the ONE `DBModel._insert` grouping path (`buildInsert` handles ON CONFLICT for
+ * both a single record and a batch). A single-record `records` array is a one-group createMany that
+ * emits the SAME statement `_insert` does for a single upsert.
+ *
+ * Parity scope (the v1/v2 SQL-parity rule, per dialect — NOT a blanket "byte-identical to v1"): on
+ * **Postgres** the emitted upsert INSERT is byte-identical to v1 (`compileInsertMany` copies the v1
+ * `buildInsert` verbatim; PG stays base-class tuple/placeholder form). On **MySQL / SQLite** the v2
+ * form is the JSON-array single-param shape (`json_each` / `JSON_TABLE`), which is DELIBERATELY NOT
+ * byte-identical to v1's per-row placeholder expansion — it is the established v2 shape the conformance
+ * corpus freezes (#64/#65), executing to the same rows. So: pg = v1-byte-identical; mysql/sqlite = the
+ * v2 JSON-array form (equivalent result, distinct text).
+ *
+ * @param options the `compileCreateManyBundle` options (records / rawRecords / sqlCastMap / onConflict /
+ *   onConflictUpdate / onConflictIgnore / returning / pk) — already serialized as `DBModel._insert`
+ *   holds them.
+ */
+function compileCreateBundle(modelClass, name, options, dialect = 'sqlite', columnsOptions) {
+    const resolveColumnType = modelColumnResolver(modelClass, columnsOptions);
+    return (0, write_bundle_1.compileCreateManyBundle)(name, options, dialect, resolveColumnType);
+}
+/** Compile a decorated model's `updateMany` into a batch write {@link SqlBundle} (`compileUpdateManyBundle`). */
+function compileUpdateBundle(name, options, dialect = 'sqlite') {
+    return (0, write_bundle_1.compileUpdateManyBundle)(name, options, dialect);
+}
+/**
+ * Compile a decorated model's `deleteMany` into a batch write {@link SqlBundle} (`compileDeleteManyBundle`):
+ * a PK-set IN-list DELETE (single key) or one DELETE per composite-key group. `keyColumns` +
+ * `returning` carry straight through.
+ */
+function compileDeleteBundle(name, options, dialect = 'sqlite') {
+    return (0, write_bundle_1.compileDeleteManyBundle)(name, options, dialect);
+}
+/**
+ * Build a {@link KeyTypeResolver} from a decorated model's `static columns` SoT — `(table, column) →`
+ * the de-box bc scalar of that key column ({@link import('./coltype').keyArrayElemScalar}). Threaded into
+ * {@link relationReadAuthoring} so each relation's `pluck` key array is stamped with the type its
+ * READ-materialized key value carries. Returns `undefined` when the model declares no columns.
+ */
+function relationKeyTypeResolver(modelClass, columnsOptions) {
+    const columns = deriveModelColumns(modelClass, columnsOptions);
+    if (Object.keys(columns).length === 0)
+        return undefined;
+    return (table, column) => {
+        const sqlType = columns[table]?.[column];
+        if (sqlType === undefined) {
+            throw new Error(`decorator-adapter: relation key column '${table}.${column}' has no declared type in the model's ` +
+                `static columns — cannot stamp the key array's de-box element type (no-assume, no-fallback).`);
+        }
+        return (0, coltype_1.keyArrayElemScalar)(sqlType);
+    };
+}
+/** The fail-closed column-type resolver for a decorated model (its `static columns` SoT), or `undefined` if it has no columns. */
+function modelColumnResolver(modelClass, columnsOptions) {
+    const columns = deriveModelColumns(modelClass, columnsOptions);
+    const tables = Object.keys(columns);
+    if (tables.length === 0)
+        return undefined;
+    const map = new Map();
+    for (const [t, cols] of Object.entries(columns))
+        map.set(t, new Map(Object.entries(cols)));
+    return (0, coltype_1.columnTypeResolverFromColumnMap)(map);
+}
+// ── 4. Relation authoring generation (@hasMany / @belongsTo / @hasOne → RelationDecl → RelationOp) ──
+/**
+ * Translate a decorated model's `@hasMany` / `@belongsTo` / `@hasOne` {@link RelationMeta} registry
+ * into SCP {@link RelationDecl}s. Single AND composite keys are supported: the decorator's
+ * `keysFactory` resolves lazily (forward refs) to `[srcCol, tgtCol]` (single) or `[[…],[…]]`
+ * (composite); the target table + projection come from the target model's `@column` metadata (the
+ * relation projects the child's OWN columns). Per-parent `order` / `limit` (hasMany window) and
+ * `hardLimit` carry from the decorator `options`.
+ *
+ * @param modelClass the parent (source) `@model` class.
+ * @param resolveTargetModel model NAME → the target `@model` class (the decorator records the target
+ *   model NAME on the key column; the caller supplies the registry — same lazy-resolution shape v1's
+ *   `_loadRelation` uses).
+ */
+function deriveRelationDecls(modelClass, resolveTargetModel, dialect = 'sqlite') {
+    return (0, decorators_1.getRelationMeta)(modelClass).map((rel) => relationDeclOf(rel, resolveTargetModel, dialect).decl);
+}
+/**
+ * Translate ONE {@link RelationMeta} → a {@link RelationDecl} (single or composite key) AND the
+ * resolved target model (so a caller can bake the child's de-box materializers from the TARGET
+ * model's `static columns` — the relation projects the child's own columns).
+ */
+function relationDeclOf(rel, resolveTargetModel, dialect = 'sqlite') {
+    const parsed = parseKeys(rel.keysFactory());
+    const targetModel = resolveTargetModel(parsed.targetModelName);
+    const targetTable = tableNameOf(targetModel);
+    const select = targetProjection(targetModel);
+    const order = rel.options?.order ? (0, Column_1.orderToString)(rel.options.order()) : undefined;
+    const base = {
+        name: rel.propertyKey,
+        kind: rel.type,
+        targetTable,
+        select,
+        dialect,
+        ...(order !== undefined ? { order } : {}),
+        ...(rel.options?.limit !== undefined ? { limit: rel.options.limit } : {}),
+        ...(rel.options?.hardLimit !== undefined ? { hardLimit: rel.options.hardLimit } : {}),
+    };
+    const decl = parsed.composite
+        ? { ...base, parentKeys: parsed.sourceKeys, targetKeys: parsed.targetKeys }
+        : { ...base, parentKey: parsed.sourceKeys[0], targetKey: parsed.targetKeys[0] };
+    return { decl, targetModel };
+}
+/**
+ * Compile a decorated model's relation registry into ready {@link RelationOp}s (one per relation). Each
+ * op's child-column de-box materializers are baked from the TARGET model's `static columns` (the same
+ * resolution the primary read uses) — ZERO per-read introspection.
+ */
+function compileRelationOps(modelClass, resolveTargetModel, dialect = 'sqlite', columnsOptions) {
+    const ops = {};
+    for (const rel of (0, decorators_1.getRelationMeta)(modelClass)) {
+        const { decl, targetModel } = relationDeclOf(rel, resolveTargetModel, dialect);
+        ops[decl.name] = (0, relation_1.compileRelationOp)(decl, modelColumnResolver(targetModel, columnsOptions));
+    }
+    return ops;
+}
+/** Parse the decorator `keysFactory()` result (single pair or composite) into src/target column lists. */
+function parseKeys(keys) {
+    const arr = keys;
+    const composite = Array.isArray(arr[0]);
+    if (composite) {
+        const pairs = arr;
+        return {
+            composite: true,
+            sourceKeys: pairs.map((p) => p[0].columnName),
+            targetKeys: pairs.map((p) => p[1].columnName),
+            targetModelName: pairs[0][1].modelName,
+        };
+    }
+    const [src, tgt] = arr;
+    return { composite: false, sourceKeys: [src.columnName], targetKeys: [tgt.columnName], targetModelName: tgt.modelName };
+}
+/** The target model's projected columns (its own `@column` DB column names — the relation child props). */
+function targetProjection(targetModel) {
+    const meta = (0, decorators_1.getColumnMeta)(targetModel);
+    if (meta === undefined)
+        return [];
+    return Array.from(meta.values()).map((m) => m.columnName);
+}
+//# sourceMappingURL=decorator-adapter.js.map

package/dist/scp/decorator-adapter.js.map

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

package/dist/scp/emit/emitter.d.ts

@@ -0,0 +1,108 @@
+/**
+ * litedbmodel v2 SCP — the decorator/metadata → SCP-restricted TS LOWERING EMITTER.
+ *
+ * This is the middle of the settled model (CLAUDE.md §1):
+ *
+ * ```
+ * ORM user: decorated models + DECLARED endpoints (no SQL)      ← src/decorators.ts + ./endpoint
+ *    ↓  emitBehaviorModule — THIS module
+ * SCP-restricted TS: `@behavior static` methods calling the ONE `@leaf` catalog (`Db`), with the
+ * dialect SQL already baked in by `makesql`
+ *    ↓  bc generate --from
+ * go / rust / py / php / ts native modules — bc wires the leaves automatically
+ * ```
+ *
+ * ## It compiles nothing of its own
+ *
+ * Every artifact the emitter puts in the emitted source comes from an EXISTING aggregation point —
+ * the emitter only RENDERS them as TypeScript:
+ *
+ *  | emitted thing                | comes from                                                      |
+ *  |------------------------------|-----------------------------------------------------------------|
+ *  | read SQL + param order       | `makesql/compile-select.compileSelect`                           |
+ *  | WHERE text (whole / fragment)| `makesql/compile.compileWhere` → `DBConditions`                  |
+ *  | static IN-list membership    | `makesql/json-array.inListPredicate` (PG `= ANY(?)`, #46)        |
+ *  | write SQL + param order      | `makesql/tx.compileWriteNode` (INSERT/UPDATE/DELETE + batch)     |
+ *  | relation batch SQL + keys    | `relation.compileRelationOp` (+ `parentKeyCols`/`targetKeyCols`) |
+ *  | relation hard-limit guard    | `relation.relationGuard` (the compiled op's resolved cap)         |
+ *  | row types                    | `makesql/outtype.deriveReadRow` over the model's `@column` SoT   |
+ *  | column SQL types             | `decorator-adapter.deriveModelColumns` / `modelColumnResolver`   |
+ *  | relation declarations        | `decorator-adapter.relationDeclOf`                               |
+ *  | find hard-limit cap          | `limit-config.resolveFindHardLimit`                              |
+ *  | the leaf catalog             | `leaf-transport.Db` (imported by the emitted module)             |
+ *
+ * ## How a parameter reaches the SQL
+ *
+ * The builders bind VALUES: they push whatever value a condition/port carried into `params` in the
+ * exact order the `?`s appear. The emitter therefore hands them a {@link ParamRef} SENTINEL instead
+ * of a value and reads the sentinels back out of `params` — so the emitted `params` array is the
+ * builders' own binding order, with each slot rendered as the method parameter it stands for. A slot
+ * that came back as a plain value (a QUERY view's own fragment params) renders as a literal.
+ *
+ * ## SKIP / dynamic WHERE (CLAUDE.md §2 — settled)
+ *
+ * A predicate declared `optional` is present-or-absent PER CALL, so the final SQL can only be
+ * determined at execution time. The emitter therefore does NOT bake it: it passes the WHERE as
+ * FRAGMENTS — SQL text + params, and a skipped fragment is simply omitted — and the `executeSQL`
+ * leaf assembles the survivors when it runs ({@link import('../leaves').assembleDynamicWhere}); the
+ * `?`→`$N` render happens after that, on the final SQL. There is no intermediate IR vocabulary: a
+ * fragment is `{sql, params}` and nothing else, and a skipped one evaluates to `null` (bc's `cond` is
+ * lazy, so a dropped fragment's params are never evaluated).
+ *
+ * A statement with NO optional predicate carries no plan at all — its WHERE is lowered into the
+ * static `sql` at emit time (native-clean). One path, chosen per statement.
+ */
+import { type DeriveColumnsOptions, type ModelClassLike } from '../decorator-adapter';
+import type { DialectName } from '../dialect';
+import type { EndpointSet } from './endpoint';
+/** What to emit. */
+export interface EmitSpec {
+    /** The emitted class name — the `bc generate --behavior` argument. */
+    readonly behavior: string;
+    /** The dialect whose SQL is baked into the emitted source. */
+    readonly dialect: DialectName;
+    /**
+     * The module specifier the emitted source imports `Db` from — the ONE `@leaf` catalog
+     * (`src/scp/leaf-transport`). It must resolve FROM the emitted file's own location, because
+     * `bc generate --from` type-checks the emitted source.
+     */
+    readonly leafImport: string;
+    /** The declared endpoints — one `@behavior static` method each, in declaration order. */
+    readonly endpoints: EndpointSet;
+    /** Model NAME → model class, for resolving a relation's target model (as `deriveRelationDecls` takes). */
+    readonly models?: (modelName: string) => ModelClassLike;
+    /** Per-column SQL-type overrides passed through to {@link deriveModelColumns}. */
+    readonly columnOptions?: DeriveColumnsOptions;
+}
+/** One emitted endpoint's call contract — what a caller passes and what it gets back. */
+export interface EmittedEndpoint {
+    readonly name: string;
+    /** The emitted method's parameters, in signature order (the generated module's input scope keys). */
+    readonly params: readonly {
+        readonly name: string;
+        readonly type: string;
+    }[];
+    /** The emitted method's declared return type. */
+    readonly returnType: string;
+    /**
+     * The `findHardLimit` cap baked into this read's `LIMIT cap + 1` bounded fetch, when one was
+     * configured and the endpoint declared no explicit limit. SCP has no throw, so the read boundary
+     * enforces it post-fetch with {@link import('../limit-config').assertFindHardLimit} — the same
+     * split the relation twin uses (`runRelationOp` throws off the op's baked `hardLimit`).
+     */
+    readonly findHardLimit?: number;
+}
+/** The emitter's output. */
+export interface EmitResult {
+    /** The SCP-restricted TypeScript source (what `bc generate --from` reads). */
+    readonly source: string;
+    /** Per-endpoint call contracts, in emission order. */
+    readonly endpoints: readonly EmittedEndpoint[];
+}
+/**
+ * Lower a set of declared endpoints to SCP-restricted TypeScript. The result's `source` is ordinary
+ * `tsc --strict` TypeScript (that is bc's authoring requirement) whose only imports are bc's
+ * authoring markers and the library's ONE leaf catalog.
+ */
+export declare function emitBehaviorModule(spec: EmitSpec): EmitResult;
+//# sourceMappingURL=emitter.d.ts.map

package/dist/scp/emit/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../../src/scp/emit/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAcH,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAQV,WAAW,EAYZ,MAAM,YAAY,CAAC;AAIpB,oBAAoB;AACpB,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,0GAA0G;IAC1G,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,cAAc,CAAC;IACxD,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;CAC/C;AAED,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7E,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,4BAA4B;AAC5B,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAsBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAM7D"}