@syncular/core 0.0.1-100

package/dist/scopes/index.js

@@ -0,0 +1,67 @@
+/**
+ * @syncular/core - Scope types, patterns, and utilities
+ *
+ * Scope patterns define how data is partitioned for sync.
+ * Scopes are stored as JSONB on changes for flexible filtering.
+ * Patterns use `{placeholder}` syntax to extract or inject values.
+ */
+// ── Pattern parsing (internal helpers) ───────────────────────────────
+/**
+ * Extract the placeholder name from a pattern.
+ * Returns null if the pattern doesn't contain a valid placeholder.
+ */
+function extractPlaceholder(pattern) {
+    const match = pattern.match(/^(.*?)\{(\w+)\}(.*)$/);
+    if (!match)
+        return null;
+    return {
+        prefix: match[1],
+        placeholder: match[2],
+        suffix: match[3],
+    };
+}
+/**
+ * Extract the placeholder name from a pattern.
+ */
+function getPlaceholderName(pattern) {
+    const parsed = extractPlaceholder(pattern);
+    return parsed?.placeholder ?? null;
+}
+/**
+ * Normalize scope definitions to a pattern-to-column map.
+ *
+ * @example
+ * normalizeScopes(['user:{user_id}'])
+ * // → { 'user:{user_id}': 'user_id' }
+ */
+export function normalizeScopes(scopes) {
+    const result = {};
+    for (const scope of scopes) {
+        if (typeof scope === 'string') {
+            const placeholder = getPlaceholderName(scope);
+            if (!placeholder) {
+                throw new Error(`Scope pattern "${scope}" must contain a placeholder like {column_name}`);
+            }
+            result[scope] = placeholder;
+        }
+        else {
+            result[scope.pattern] = scope.column;
+        }
+    }
+    return result;
+}
+// ── Value operations (public) ────────────────────────────────────────
+/**
+ * Extract variable names from a scope pattern.
+ *
+ * @example
+ * extractScopeVars('project:{project_id}') // ['project_id']
+ * extractScopeVars('event_date:{year}:{month}') // ['year', 'month']
+ */
+export function extractScopeVars(pattern) {
+    const matches = pattern.match(/\{([^}]+)\}/g);
+    if (!matches)
+        return [];
+    return matches.map((m) => m.slice(1, -1));
+}
+//# sourceMappingURL=index.js.map

package/dist/scopes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8CH,0IAAwE;AAExE;;;GAGG;AACH,SAAS,kBAAkB,CAAC,OAAe,EAIlC;IACP,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE;QACjB,WAAW,EAAE,KAAK,CAAC,CAAC,CAAE;QACtB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE;KAClB,CAAC;AAAA,CACH;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,OAAe,EAAiB;IAC1D,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC;AAAA,CACpC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAyB,EACD;IACxB,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAC9C,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,iDAAiD,CACzE,CAAC;YACJ,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACf;AAED,4JAAwE;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB,EAAY;IAChE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAAA,CAC3C"}

package/dist/snapshot-chunks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @syncular/core - Snapshot chunk encoding helpers
+ */
+export declare const SYNC_SNAPSHOT_CHUNK_ENCODING = "json-row-frame-v1";
+export type SyncSnapshotChunkEncoding = typeof SYNC_SNAPSHOT_CHUNK_ENCODING;
+export declare const SYNC_SNAPSHOT_CHUNK_COMPRESSION = "gzip";
+export type SyncSnapshotChunkCompression = typeof SYNC_SNAPSHOT_CHUNK_COMPRESSION;
+/**
+ * Encode rows as framed JSON bytes without the format header.
+ */
+export declare function encodeSnapshotRowFrames(rows: readonly unknown[]): Uint8Array;
+/**
+ * Encode rows as framed JSON bytes with a format header.
+ *
+ * Format:
+ * - 4-byte magic header ("SRF1")
+ * - repeated frames of:
+ *   - 4-byte big-endian payload byte length
+ *   - UTF-8 JSON payload
+ */
+export declare function encodeSnapshotRows(rows: readonly unknown[]): Uint8Array;
+/**
+ * Decode framed JSON bytes into rows.
+ */
+export declare function decodeSnapshotRows(bytes: Uint8Array): unknown[];
+//# sourceMappingURL=snapshot-chunks.d.ts.map

package/dist/snapshot-chunks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-chunks.d.ts","sourceRoot":"","sources":["../src/snapshot-chunks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAChE,MAAM,MAAM,yBAAyB,GAAG,OAAO,4BAA4B,CAAC;AAE5E,eAAO,MAAM,+BAA+B,SAAS,CAAC;AACtD,MAAM,MAAM,4BAA4B,GACtC,OAAO,+BAA+B,CAAC;AAWzC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,UAAU,CA2B5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,UAAU,CASvE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,EAAE,CAoC/D"}

package/dist/snapshot-chunks.js

@@ -0,0 +1,89 @@
+/**
+ * @syncular/core - Snapshot chunk encoding helpers
+ */
+export const SYNC_SNAPSHOT_CHUNK_ENCODING = 'json-row-frame-v1';
+export const SYNC_SNAPSHOT_CHUNK_COMPRESSION = 'gzip';
+const SNAPSHOT_ROW_FRAME_MAGIC = new Uint8Array([0x53, 0x52, 0x46, 0x31]); // "SRF1"
+const FRAME_LENGTH_BYTES = 4;
+const MAX_FRAME_BYTE_LENGTH = 0xffff_ffff;
+function normalizeRowJson(row) {
+    const serialized = JSON.stringify(row);
+    return serialized === undefined ? 'null' : serialized;
+}
+/**
+ * Encode rows as framed JSON bytes without the format header.
+ */
+export function encodeSnapshotRowFrames(rows) {
+    const encoder = new TextEncoder();
+    const payloads = [];
+    let totalByteLength = 0;
+    for (const row of rows) {
+        const payload = encoder.encode(normalizeRowJson(row));
+        if (payload.length > MAX_FRAME_BYTE_LENGTH) {
+            throw new Error(`Snapshot row payload exceeds ${MAX_FRAME_BYTE_LENGTH} bytes`);
+        }
+        payloads.push(payload);
+        totalByteLength += FRAME_LENGTH_BYTES + payload.length;
+    }
+    const encoded = new Uint8Array(totalByteLength);
+    const view = new DataView(encoded.buffer, encoded.byteOffset, encoded.length);
+    let offset = 0;
+    for (const payload of payloads) {
+        view.setUint32(offset, payload.length, false);
+        offset += FRAME_LENGTH_BYTES;
+        encoded.set(payload, offset);
+        offset += payload.length;
+    }
+    return encoded;
+}
+/**
+ * Encode rows as framed JSON bytes with a format header.
+ *
+ * Format:
+ * - 4-byte magic header ("SRF1")
+ * - repeated frames of:
+ *   - 4-byte big-endian payload byte length
+ *   - UTF-8 JSON payload
+ */
+export function encodeSnapshotRows(rows) {
+    const framedRows = encodeSnapshotRowFrames(rows);
+    const totalByteLength = SNAPSHOT_ROW_FRAME_MAGIC.length + framedRows.length;
+    const encoded = new Uint8Array(totalByteLength);
+    encoded.set(SNAPSHOT_ROW_FRAME_MAGIC, 0);
+    encoded.set(framedRows, SNAPSHOT_ROW_FRAME_MAGIC.length);
+    return encoded;
+}
+/**
+ * Decode framed JSON bytes into rows.
+ */
+export function decodeSnapshotRows(bytes) {
+    if (bytes.length < SNAPSHOT_ROW_FRAME_MAGIC.length) {
+        throw new Error('Snapshot chunk payload is too small');
+    }
+    for (let index = 0; index < SNAPSHOT_ROW_FRAME_MAGIC.length; index += 1) {
+        const expected = SNAPSHOT_ROW_FRAME_MAGIC[index];
+        const actual = bytes[index];
+        if (actual !== expected) {
+            throw new Error('Unexpected snapshot chunk format');
+        }
+    }
+    const rows = [];
+    const decoder = new TextDecoder();
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+    let offset = SNAPSHOT_ROW_FRAME_MAGIC.length;
+    while (offset < bytes.length) {
+        if (offset + FRAME_LENGTH_BYTES > bytes.length) {
+            throw new Error('Snapshot chunk payload ended mid-frame header');
+        }
+        const payloadLength = view.getUint32(offset, false);
+        offset += FRAME_LENGTH_BYTES;
+        if (offset + payloadLength > bytes.length) {
+            throw new Error('Snapshot chunk payload ended mid-frame body');
+        }
+        const payload = bytes.subarray(offset, offset + payloadLength);
+        offset += payloadLength;
+        rows.push(JSON.parse(decoder.decode(payload)));
+    }
+    return rows;
+}
+//# sourceMappingURL=snapshot-chunks.js.map

package/dist/snapshot-chunks.js.map

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

package/dist/telemetry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @syncular/core - Runtime telemetry abstraction
+ *
+ * Provides vendor-neutral logging, tracing, and metrics interfaces so
+ * Syncular libraries can emit telemetry without coupling to a specific SDK.
+ */
+/**
+ * Supported log levels.
+ */
+export type SyncTelemetryLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Primitive attribute value used by traces and metrics.
+ */
+export type SyncTelemetryAttributeValue = string | number | boolean;
+/**
+ * Attribute bag used by traces and metrics.
+ */
+export type SyncTelemetryAttributes = Record<string, SyncTelemetryAttributeValue>;
+/**
+ * Structured sync log event.
+ */
+export interface SyncTelemetryEvent {
+    event: string;
+    level?: SyncTelemetryLevel;
+    userId?: string;
+    durationMs?: number;
+    rowCount?: number;
+    resetRequired?: boolean;
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Span creation options.
+ */
+export interface SyncSpanOptions {
+    name: string;
+    op?: string;
+    attributes?: SyncTelemetryAttributes;
+}
+/**
+ * Span API exposed to Syncular internals.
+ */
+export interface SyncSpan {
+    setAttribute(name: string, value: SyncTelemetryAttributeValue): void;
+    setAttributes(attributes: SyncTelemetryAttributes): void;
+    setStatus(status: 'ok' | 'error'): void;
+}
+/**
+ * Tracing interface.
+ */
+export interface SyncTracer {
+    startSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T;
+}
+/**
+ * Metric record options.
+ */
+export interface SyncMetricOptions {
+    attributes?: SyncTelemetryAttributes;
+    unit?: string;
+}
+/**
+ * Metrics interface.
+ */
+export interface SyncMetrics {
+    count(name: string, value?: number, options?: SyncMetricOptions): void;
+    gauge(name: string, value: number, options?: SyncMetricOptions): void;
+    distribution(name: string, value: number, options?: SyncMetricOptions): void;
+}
+/**
+ * Unified telemetry interface.
+ */
+export interface SyncTelemetry {
+    log(event: SyncTelemetryEvent): void;
+    tracer: SyncTracer;
+    metrics: SyncMetrics;
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+/**
+ * Create console-backed default telemetry (logs only; no-op tracing/metrics).
+ */
+export declare function createDefaultSyncTelemetry(): SyncTelemetry;
+/**
+ * Get currently configured telemetry backend.
+ */
+export declare function getSyncTelemetry(): SyncTelemetry;
+/**
+ * Replace active telemetry backend.
+ */
+export declare function configureSyncTelemetry(telemetry: SyncTelemetry): void;
+/**
+ * Reset telemetry backend to default console implementation.
+ */
+export declare function resetSyncTelemetry(): void;
+/**
+ * Capture an exception through the active telemetry backend.
+ */
+export declare function captureSyncException(error: unknown, context?: Record<string, unknown>): void;
+/**
+ * Start a span through the active telemetry backend.
+ */
+export declare function startSyncSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T;
+/**
+ * Record a counter metric through the active telemetry backend.
+ */
+export declare function countSyncMetric(name: string, value?: number, options?: SyncMetricOptions): void;
+/**
+ * Record a gauge metric through the active telemetry backend.
+ */
+export declare function gaugeSyncMetric(name: string, value: number, options?: SyncMetricOptions): void;
+/**
+ * Record a distribution metric through the active telemetry backend.
+ */
+export declare function distributionSyncMetric(name: string, value: number, options?: SyncMetricOptions): void;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

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

package/dist/telemetry.js

@@ -0,0 +1,113 @@
+/**
+ * @syncular/core - Runtime telemetry abstraction
+ *
+ * Provides vendor-neutral logging, tracing, and metrics interfaces so
+ * Syncular libraries can emit telemetry without coupling to a specific SDK.
+ */
+const noopSpan = {
+    setAttribute() { },
+    setAttributes() { },
+    setStatus() { },
+};
+const noopTracer = {
+    startSpan(_options, callback) {
+        return callback(noopSpan);
+    },
+};
+const noopMetrics = {
+    count() { },
+    gauge() { },
+    distribution() { },
+};
+function createConsoleLogger() {
+    const isNode = typeof globalThis !== 'undefined' &&
+        typeof globalThis.setImmediate === 'function';
+    const defer = isNode
+        ? (fn) => globalThis.setImmediate(fn)
+        : (fn) => setTimeout(fn, 0);
+    return (event) => {
+        defer(() => {
+            const level = event.level ?? (event.error ? 'error' : 'info');
+            const payload = {
+                timestamp: new Date().toISOString(),
+                level,
+                ...event,
+            };
+            console.log(JSON.stringify(payload));
+        });
+    };
+}
+/**
+ * Create console-backed default telemetry (logs only; no-op tracing/metrics).
+ */
+export function createDefaultSyncTelemetry() {
+    const logger = createConsoleLogger();
+    return {
+        log(event) {
+            logger(event);
+        },
+        tracer: noopTracer,
+        metrics: noopMetrics,
+        captureException(error, context) {
+            const message = error instanceof Error
+                ? error.message
+                : `Unknown error: ${String(error)}`;
+            logger({
+                event: 'sync.exception',
+                level: 'error',
+                error: message,
+                ...(context ?? {}),
+            });
+        },
+    };
+}
+let activeSyncTelemetry = createDefaultSyncTelemetry();
+/**
+ * Get currently configured telemetry backend.
+ */
+export function getSyncTelemetry() {
+    return activeSyncTelemetry;
+}
+/**
+ * Replace active telemetry backend.
+ */
+export function configureSyncTelemetry(telemetry) {
+    activeSyncTelemetry = telemetry;
+}
+/**
+ * Reset telemetry backend to default console implementation.
+ */
+export function resetSyncTelemetry() {
+    activeSyncTelemetry = createDefaultSyncTelemetry();
+}
+/**
+ * Capture an exception through the active telemetry backend.
+ */
+export function captureSyncException(error, context) {
+    activeSyncTelemetry.captureException(error, context);
+}
+/**
+ * Start a span through the active telemetry backend.
+ */
+export function startSyncSpan(options, callback) {
+    return activeSyncTelemetry.tracer.startSpan(options, callback);
+}
+/**
+ * Record a counter metric through the active telemetry backend.
+ */
+export function countSyncMetric(name, value, options) {
+    activeSyncTelemetry.metrics.count(name, value, options);
+}
+/**
+ * Record a gauge metric through the active telemetry backend.
+ */
+export function gaugeSyncMetric(name, value, options) {
+    activeSyncTelemetry.metrics.gauge(name, value, options);
+}
+/**
+ * Record a distribution metric through the active telemetry backend.
+ */
+export function distributionSyncMetric(name, value, options) {
+    activeSyncTelemetry.metrics.distribution(name, value, options);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/transforms.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @syncular/core - Data transformation hooks
+ *
+ * Provides interfaces for field-level transformations (e.g., encryption/decryption)
+ * that can be applied during sync operations.
+ */
+/**
+ * Direction of the transformation.
+ * - 'toClient': Server → Client (e.g., decrypt for client)
+ * - 'toServer': Client → Server (e.g., encrypt for server)
+ */
+export type TransformDirection = 'toClient' | 'toServer';
+/**
+ * Context passed to transform functions.
+ */
+export interface TransformContext {
+    /** Direction of transformation */
+    direction: TransformDirection;
+    /** Scope name */
+    scope: string;
+    /** Table name */
+    table: string;
+    /** Row ID */
+    rowId: string;
+    /** User ID performing the operation */
+    userId: string;
+}
+/**
+ * A field transformer handles transformation of a single field.
+ *
+ * @example
+ * const secretNotesTransformer: FieldTransformer = {
+ *   field: 'secret_notes',
+ *   async transform(value, ctx) {
+ *     const key = await getUserEncryptionKey(ctx.userId);
+ *     return ctx.direction === 'toClient'
+ *       ? decrypt(value as string, key)
+ *       : encrypt(value as string, key);
+ *   }
+ * };
+ */
+export interface FieldTransformer {
+    /** Field name to transform */
+    field: string;
+    /**
+     * Transform the field value.
+     * @param value - Current field value
+     * @param ctx - Transform context
+     * @returns Transformed value
+     */
+    transform(value: unknown, ctx: TransformContext): Promise<unknown> | unknown;
+}
+/**
+ * Configuration for transforms on a scope.
+ */
+export interface ScopeTransformConfig {
+    /** Scope name this config applies to */
+    scope: string;
+    /** Field transformers for this scope */
+    fields?: FieldTransformer[];
+}
+/**
+ * Registry for managing data transforms.
+ *
+ * @example
+ * const transforms = new TransformRegistry();
+ *
+ * transforms.register({
+ *   scope: 'tasks',
+ *   fields: [{
+ *     field: 'secret_notes',
+ *     async transform(value, ctx) {
+ *       const key = await getUserEncryptionKey(ctx.userId);
+ *       return ctx.direction === 'toClient'
+ *         ? decrypt(value as string, key)
+ *         : encrypt(value as string, key);
+ *     }
+ *   }]
+ * });
+ *
+ * // Apply transforms to data
+ * const transformed = await transforms.apply(
+ *   [{ id: '1', secret_notes: 'encrypted...' }],
+ *   { direction: 'toClient', scope: 'tasks', ... }
+ * );
+ */
+export declare class TransformRegistry {
+    private configs;
+    /**
+     * Register transform config for a scope.
+     * @throws If config for this scope is already registered
+     */
+    register(config: ScopeTransformConfig): void;
+    /**
+     * Unregister transform config by scope.
+     * @returns true if config was found and removed
+     */
+    unregister(scope: string): boolean;
+    /**
+     * Get config for a scope.
+     */
+    get(scope: string): ScopeTransformConfig | undefined;
+    /**
+     * Check if any transforms are registered for a scope.
+     */
+    hasTransforms(scope: string): boolean;
+    /**
+     * Get all registered configs.
+     */
+    getAll(): ScopeTransformConfig[];
+    /**
+     * Apply transforms to a single row.
+     *
+     * @param row - Row data to transform
+     * @param ctx - Transform context (without rowId, will be extracted from row)
+     * @param rowIdField - Field name for row ID (default: 'id')
+     * @returns Transformed row
+     */
+    applyToRow<T extends Record<string, unknown>>(row: T, ctx: Omit<TransformContext, 'rowId'>, rowIdField?: string): Promise<T>;
+    /**
+     * Apply transforms to multiple rows.
+     *
+     * @param rows - Array of rows to transform
+     * @param ctx - Transform context (without rowId)
+     * @param rowIdField - Field name for row ID (default: 'id')
+     * @returns Transformed rows
+     */
+    apply<T extends Record<string, unknown>>(rows: T[], ctx: Omit<TransformContext, 'rowId'>, rowIdField?: string): Promise<T[]>;
+    /**
+     * Apply transforms to a mutation payload.
+     *
+     * @param payload - Mutation payload (may be partial row)
+     * @param ctx - Full transform context
+     * @returns Transformed payload
+     */
+    applyToPayload<T extends Record<string, unknown>>(payload: T | null, ctx: TransformContext): Promise<T | null>;
+    /**
+     * Clear all registered configs.
+     */
+    clear(): void;
+}
+/**
+ * Create a new transform registry.
+ */
+export declare function createTransformRegistry(): TransformRegistry;
+//# sourceMappingURL=transforms.d.ts.map

package/dist/transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../src/transforms.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC9E;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAgD;IAE/D;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAO3C;IAED;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEnD;IAED;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGpC;IAED;;OAEG;IACH,MAAM,IAAI,oBAAoB,EAAE,CAE/B;IAED;;;;;;;OAOG;IACG,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,GAAG,EAAE,CAAC,EACN,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,EACpC,UAAU,SAAO,GAChB,OAAO,CAAC,CAAC,CAAC,CA4BZ;IAED;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,IAAI,EAAE,CAAC,EAAE,EACT,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,EACpC,UAAU,SAAO,GAChB,OAAO,CAAC,CAAC,EAAE,CAAC,CASd;IAED;;;;;;OAMG;IACG,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,OAAO,EAAE,CAAC,GAAG,IAAI,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CA4BnB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAEZ;CACF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D"}