@rocicorp/zero 1.11.0-canary.4 → 1.11.0-canary.41

package/out/zero-cache/src/services/view-syncer/schema/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../../../../../zero-cache/src/services/view-syncer/schema/types.ts"],"sourcesContent":["import {jsonValueSchema} from '../../../../../shared/src/bigint-json.ts';\nimport {jsonSchema} from '../../../../../shared/src/json-schema.ts';\nimport * as v from '../../../../../shared/src/valita.ts';\nimport {astSchema} from '../../../../../zero-protocol/src/ast.ts';\nimport {versionFromLexi, versionToLexi} from '../../../types/lexi-version.ts';\nimport {\n  majorVersionToString,\n  stateVersionFromString,\n} from '../../../types/state-version.ts';\nimport {ttlClockSchema} from '../ttl-clock.ts';\nimport type {QueriesRow} from './cvr.ts';\n\nexport const cvrVersionSchema = v.object({\n  /**\n   * The database `stateVersion` with which the rows in the CVR are consistent.\n   */\n  stateVersion: v.string(), // LexiVersion\n\n  /**\n   * `configVersion` is subversion of `stateVersion` that is initially absent for each\n   * `stateVersion`, and incremented for configuration changes that affect the contents\n   * of the CVR such as:\n   *\n   * * query set changes\n   * * query transformation changes (which may happen for changes\n   *   in server-side logic or authorization policies)\n   *\n   * Such configuration changes are always correlated with a change to one or more\n   * `/meta/...` records in the CVR, often (but not always) with corresponding\n   * patches in `/patches/meta/...`.\n   *\n   * When the `stateVersion` moves forward, the `minorVersion` is reset to absent.\n   * In this manner it behaves like the analogous concept in semantic versioning.\n   */\n  configVersion: v.number().optional(),\n});\n\nexport type CVRVersion = v.Infer<typeof cvrVersionSchema>;\n\nexport const EMPTY_CVR_VERSION: CVRVersion = {\n  stateVersion: majorVersionToString(0),\n} as const;\n\nexport function oneAfter(v: NullableCVRVersion): CVRVersion {\n  return v === null\n    ? {stateVersion: majorVersionToString(0)}\n    : {\n        stateVersion: v.stateVersion,\n        configVersion: (v.configVersion ?? 0) + 1,\n      };\n}\n\nexport type NullableCVRVersion = CVRVersion | null;\n\nexport function cmpVersions(\n  a: NullableCVRVersion,\n  b: NullableCVRVersion,\n): number {\n  return a === null && b === null\n    ? 0\n    : a === null\n      ? -1\n      : b === null\n        ? 1\n        : a.stateVersion < b.stateVersion\n          ? -1\n          : a.stateVersion > b.stateVersion\n            ? 1\n            : (a.configVersion ?? 0) - (b.configVersion ?? 0);\n}\n\nexport function maxVersion(a: CVRVersion, b?: CVRVersion): CVRVersion {\n  return !b ? a : cmpVersions(b, a) > 0 ? b : a;\n}\n\nexport function versionToCookie(v: CVRVersion): string {\n  return versionString(v);\n}\n\nexport function versionToNullableCookie(v: NullableCVRVersion): string | null {\n  return v === null ? null : versionToCookie(v);\n}\n\nexport function cookieToVersion(cookie: string | null): NullableCVRVersion {\n  if (cookie === null) {\n    return null;\n  }\n  return versionFromString(cookie);\n}\n\n// Last Active tracking.\n\nexport const cvrIDSchema = v.object({id: v.string()});\nexport type CvrID = v.Infer<typeof cvrIDSchema>;\n\nconst cvrRecordSchema = v.object({\n  /**\n   * CVR records store the CVRVersion at which the record was last patched into\n   * the CVR, which corresponds with a patch row that is cleaned up when the\n   * record is changed (updated, deleted, and re-added in the case of rows).\n   *\n   * Tombstones are stored for row records but not for config records. This means\n   * that \"orphaned\" delete patches for config records may exist, and therefore\n   * scans of config patches must always run until the end of the list. On the\n   * contrary, for row patches, the row record tombstones allow cleanup of delete\n   * patches.\n   */\n  patchVersion: cvrVersionSchema,\n});\n\nexport const clientRecordSchema = v.object({\n  /** The client ID, of which there can be multiple for a client group view. */\n  id: v.string(),\n\n  /** The client's desired query IDs. Patch information is stored in the QueryRecord. */\n  desiredQueryIDs: v.array(v.string()),\n});\n\nexport type ClientRecord = v.Infer<typeof clientRecordSchema>;\n\nexport const baseQueryRecordSchema = v.object({\n  /** The client-specified ID used to identify this query. Typically a hash. */\n  id: v.string(),\n\n  /**\n   * The hash of the query after server-side transformations, which include:\n   *\n   * * Normalization (which may differ from what the client does)\n   * * Query \"expansion\" to include primary keys and query-execution-related columns\n   * * Authorization transforms\n   *\n   * Transformations depend on conditions that are independent of the db state version,\n   * such as server-side logic and authorization policies. As such, the version of a CVR\n   * version may need to be advanced independent of db state changes. This is done\n   * via the `minorVersion` counter of the CVRVersion object, which is used to account\n   * for both changes to the query set and changes to query transformations (which are\n   * effectively remove-old-query + add-new-query).\n   *\n   * Note that the transformed AST itself is **not** stored, as the result of the previous\n   * transformation is not useful in and of itself. If the current transformation results in\n   * a different hash than that of the transformation used for the last version of the CVR,\n   * it is simply handled by invalidating the existing rows, re-executed the query with\n   * the new transformation, and advancing the CVR's `minorVersion` and this query's\n   * `transformationVersion`.\n   *\n   * Note that the transformationHash is only stored when the query has reached the \"gotten\"\n   * state. If the query is in the \"desired\" but not yet \"gotten\" state, the field is absent.\n   */\n  transformationHash: v.string().optional(),\n\n  /**\n   * The CVR version corresponding to the `transformationHash`. This essentially tracks when\n   * this version of the query was effectively added to the CVR (as opposed to the\n   * `patchVersion`, which is simply when the client was notified that its query was added\n   * to the gotten set). Catchup of clients from old CVR versions require executing all\n   * queries with a newer `transformationVersion`.\n   */\n  transformationVersion: cvrVersionSchema.optional(),\n\n  /**\n   * Hex-encoded XOR signature over `h64(JSON.stringify([schema, table, rowKey]))`\n   * of every row currently attached to this query. Maintained incrementally by\n   * `PipelineDriver` as ADDs / REMOVEs are yielded from the query's pipeline\n   * (EDITs no-op), and persisted via `CVRQueryDrivenUpdater.flush` by a\n   * signature-provider callback.\n   *\n   * Used to detect drift on re-hydration of queries containing the `Cap` operator,\n   * which intentionally does not impose ordering and thus may pick a different N-row\n   * subset on re-execution. Comparing the pre-hydration signature with the post-\n   * hydration signature lets us force a `configVersion` bump so the standard CVR-diff\n   * machinery emits the reconciling poke. Absent or `'0'` means the signature is\n   * empty (no rows currently attached).\n   */\n  rowSetSignature: v.string().optional(),\n});\n\n/**\n * Internal queries track rows in the database for internal use, such as the\n * `lastMutationID`s in the `zero.clients` table. They participate in the standard\n * invalidation / update logic for row contents, but not in the desired/got or\n * size-based quota logic for client-requested queries.\n */\nexport const internalQueryRecordSchema = baseQueryRecordSchema.extend({\n  type: v.literal('internal'),\n  ast: astSchema,\n});\n\nexport type InternalQueryRecord = v.Infer<typeof internalQueryRecordSchema>;\n\nconst clientStateSchema = v.object({\n  /**\n   * The time at which the query was last inactivated. If this undefined or\n   * missing then the query is active.\n   *\n   * Desired queries are always active and have an undefined inactivatedAt.\n   */\n  inactivatedAt: ttlClockSchema.optional(),\n\n  /**\n   * TTL, time to live in milliseconds. If the query is not updated within this\n   * time. The time to live is the time after it has become inactive. Negative\n   * values are treated as `'forever'`.\n   *\n   * We do clamp this to a maximum of 10 minutes, so that queries do not\n   * live for a very long time in the CVR.\n   */\n  ttl: v.number(),\n\n  /**\n   * The version at which the client state changed (i.e. individual `patchVersion`s).\n   */\n  version: cvrVersionSchema,\n});\n\nconst externalQueryRecordSchema = baseQueryRecordSchema.extend({\n  /**\n   * The client state for this query, which includes the inactivatedAt, ttl and\n   * version. The client state is stored in a record with the client ID as the\n   * key.\n   */\n  clientState: v.record(clientStateSchema),\n\n  // For queries, the `patchVersion` indicates when query was added to the got set,\n  // and is absent if not yet gotten.\n  patchVersion: cvrVersionSchema.optional(),\n});\n\nexport const clientQueryRecordSchema = externalQueryRecordSchema.extend({\n  type: v.literal('client'),\n\n  /** The original AST as supplied by the client. */\n  ast: astSchema,\n});\n\nexport type ClientQueryRecord = v.Infer<typeof clientQueryRecordSchema>;\n\nexport const customQueryRecordSchema = externalQueryRecordSchema.extend({\n  type: v.literal('custom'),\n  name: v.string(),\n  args: v.readonly(v.array(jsonSchema)),\n});\n\nexport type CustomQueryRecord = v.Infer<typeof customQueryRecordSchema>;\n\nexport const queryRecordSchema = v.union(\n  clientQueryRecordSchema,\n  customQueryRecordSchema,\n  internalQueryRecordSchema,\n);\n\nexport type QueryRecord = v.Infer<typeof queryRecordSchema>;\n\nexport const rowIDSchema = v.object({\n  schema: v.string(),\n  table: v.string(),\n  rowKey: v.record(jsonValueSchema),\n});\n\nexport type RowID = v.Infer<typeof rowIDSchema>;\n\nexport const rowRecordSchema = cvrRecordSchema.extend({\n  id: rowIDSchema,\n  rowVersion: v.string(), // '_0_version' of the row\n  // query hashes => refCount, or `null` for a row that was removed from the\n  // view (i.e. tombstone).\n  refCounts: v.record(v.number()).nullable(),\n});\n\nexport type RowRecord = v.Infer<typeof rowRecordSchema>;\n\nexport const patchSchema = v.object({\n  type: v.literalUnion('row', 'query'),\n  op: v.literalUnion('put', 'del'),\n});\n\nexport const putRowPatchSchema = patchSchema.extend({\n  type: v.literal('row'),\n  op: v.literal('put'),\n  id: rowIDSchema,\n  rowVersion: v.string(), // '_0_version' of the row\n});\n\nexport type PutRowPatch = v.Infer<typeof putRowPatchSchema>;\n\nexport const delRowPatchSchema = patchSchema.extend({\n  type: v.literal('row'),\n  op: v.literal('del'),\n  id: rowIDSchema,\n});\n\nexport type DelRowPatch = v.Infer<typeof delRowPatchSchema>;\n\nexport const rowPatchSchema = v.union(putRowPatchSchema, delRowPatchSchema);\n\nexport type RowPatch = v.Infer<typeof rowPatchSchema>;\n\nexport const queryPatchSchema = patchSchema.extend({\n  type: v.literal('query'),\n  id: v.string(),\n  clientID: v.string().optional(), // defined for \"desired\", undefined for \"got\"\n});\n\nexport type QueryPatch = v.Infer<typeof queryPatchSchema>;\n\nexport type PutQueryPatch = QueryPatch & {op: 'put'};\nexport type DelQueryPatch = QueryPatch & {op: 'del'};\n\nexport const metadataPatchSchema = queryPatchSchema;\n\nexport type MetadataPatch = v.Infer<typeof metadataPatchSchema>;\n\nexport function versionString(v: CVRVersion) {\n  // The separator (e.g. \":\") needs to be lexicographically greater than the\n  // storage key path separator (e.g. \"/\") so that \"01/row-hash\" is less than \"01:01/row-hash\".\n  // In particular, the traditional separator for major.minor versions (\".\") does not\n  // satisfy this quality.\n  return v.configVersion\n    ? `${v.stateVersion}:${versionToLexi(v.configVersion)}`\n    : v.stateVersion;\n}\n\nexport function versionFromString(str: string): CVRVersion {\n  const parts = str.split(':');\n  const stateVersion = parts[0];\n  switch (parts.length) {\n    case 1: {\n      stateVersionFromString(stateVersion); // Purely for validation.\n      return {stateVersion};\n    }\n    case 2: {\n      const configVersion = versionFromLexi(parts[1]);\n      if (configVersion > BigInt(Number.MAX_SAFE_INTEGER)) {\n        throw new Error(`minorVersion ${parts[1]} exceeds max safe integer`);\n      }\n      return {stateVersion, configVersion: Number(configVersion)};\n    }\n    default:\n      throw new TypeError(`Invalid version string ${str}`);\n  }\n}\n\nexport function queryRecordToQueryRow(\n  clientGroupID: string,\n  query: QueryRecord,\n): QueriesRow {\n  switch (query.type) {\n    case 'internal':\n      return {\n        clientGroupID,\n        queryHash: query.id,\n        clientAST: query.ast,\n        queryName: null,\n        queryArgs: null,\n        patchVersion: null,\n        transformationHash: query.transformationHash ?? null,\n        transformationVersion: maybeVersionString(query.transformationVersion),\n        internal: true,\n        deleted: false, // put vs del \"got\" query\n        rowSetSignature: query.rowSetSignature ?? null,\n      };\n    case 'client':\n      return {\n        clientGroupID,\n        queryHash: query.id,\n        clientAST: query.ast,\n        queryName: null,\n        queryArgs: null,\n        patchVersion: maybeVersionString(query.patchVersion),\n        transformationHash: query.transformationHash ?? null,\n        transformationVersion: maybeVersionString(query.transformationVersion),\n        internal: null,\n        deleted: false, // put vs del \"got\" query\n        rowSetSignature: query.rowSetSignature ?? null,\n      };\n    case 'custom':\n      return {\n        clientGroupID,\n        queryHash: query.id,\n        clientAST: null,\n        queryName: query.name,\n        queryArgs: query.args,\n        patchVersion: maybeVersionString(query.patchVersion),\n        transformationHash: query.transformationHash ?? null,\n        transformationVersion: maybeVersionString(query.transformationVersion),\n        internal: null,\n        deleted: false, // put vs del \"got\" query\n        rowSetSignature: query.rowSetSignature ?? null,\n      };\n  }\n}\n\nexport const maybeVersionString = (v: CVRVersion | undefined) =>\n  v ? versionString(v) : null;\n"],"mappings":"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"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../../../../../zero-cache/src/services/view-syncer/schema/types.ts"],"sourcesContent":["import {jsonValueSchema} from '../../../../../shared/src/bigint-json.ts';\nimport {jsonSchema} from '../../../../../shared/src/json-schema.ts';\nimport * as v from '../../../../../shared/src/valita.ts';\nimport {astSchema} from '../../../../../zero-protocol/src/ast.ts';\nimport {versionFromLexi, versionToLexi} from '../../../types/lexi-version.ts';\nimport {\n  majorVersionToString,\n  stateVersionFromString,\n} from '../../../types/state-version.ts';\nimport {ttlClockSchema} from '../ttl-clock.ts';\nimport type {QueriesRow} from './cvr.ts';\n\nexport const cvrVersionSchema = v.object({\n  /**\n   * The database `stateVersion` with which the rows in the CVR are consistent.\n   */\n  stateVersion: v.string(), // LexiVersion\n\n  /**\n   * `configVersion` is subversion of `stateVersion` that is initially absent for each\n   * `stateVersion`, and incremented for configuration changes that affect the contents\n   * of the CVR such as:\n   *\n   * * query set changes\n   * * query transformation changes (which may happen for changes\n   *   in server-side logic or authorization policies)\n   *\n   * Such configuration changes are always correlated with a change to one or more\n   * `/meta/...` records in the CVR, often (but not always) with corresponding\n   * patches in `/patches/meta/...`.\n   *\n   * When the `stateVersion` moves forward, the `minorVersion` is reset to absent.\n   * In this manner it behaves like the analogous concept in semantic versioning.\n   */\n  configVersion: v.number().optional(),\n});\n\nexport type CVRVersion = v.Infer<typeof cvrVersionSchema>;\n\nexport const EMPTY_CVR_VERSION: CVRVersion = {\n  stateVersion: majorVersionToString(0),\n} as const;\n\nexport function oneAfter(v: NullableCVRVersion): CVRVersion {\n  return v === null\n    ? {stateVersion: majorVersionToString(0)}\n    : {\n        stateVersion: v.stateVersion,\n        configVersion: (v.configVersion ?? 0) + 1,\n      };\n}\n\nexport type NullableCVRVersion = CVRVersion | null;\n\nexport function cmpVersions(\n  a: NullableCVRVersion,\n  b: NullableCVRVersion,\n): number {\n  return a === null && b === null\n    ? 0\n    : a === null\n      ? -1\n      : b === null\n        ? 1\n        : a.stateVersion < b.stateVersion\n          ? -1\n          : a.stateVersion > b.stateVersion\n            ? 1\n            : (a.configVersion ?? 0) - (b.configVersion ?? 0);\n}\n\nexport function maxVersion(a: CVRVersion, b?: CVRVersion): CVRVersion {\n  return !b ? a : cmpVersions(b, a) > 0 ? b : a;\n}\n\nexport function versionToCookie(v: CVRVersion): string {\n  return versionString(v);\n}\n\nexport function versionToNullableCookie(v: NullableCVRVersion): string | null {\n  return v === null ? null : versionToCookie(v);\n}\n\nexport function cookieToVersion(cookie: string | null): NullableCVRVersion {\n  if (cookie === null) {\n    return null;\n  }\n  return versionFromString(cookie);\n}\n\n// Last Active tracking.\n\nexport const cvrIDSchema = v.object({id: v.string()});\nexport type CvrID = v.Infer<typeof cvrIDSchema>;\n\nconst cvrRecordSchema = v.object({\n  /**\n   * CVR records store the CVRVersion at which the record was last patched into\n   * the CVR, which corresponds with a patch row that is cleaned up when the\n   * record is changed (updated, deleted, and re-added in the case of rows).\n   *\n   * Tombstones are stored for row records but not for config records. This means\n   * that \"orphaned\" delete patches for config records may exist, and therefore\n   * scans of config patches must always run until the end of the list. On the\n   * contrary, for row patches, the row record tombstones allow cleanup of delete\n   * patches.\n   */\n  patchVersion: cvrVersionSchema,\n});\n\nexport const clientRecordSchema = v.object({\n  /** The client ID, of which there can be multiple for a client group view. */\n  id: v.string(),\n\n  /** The client's desired query IDs. Patch information is stored in the QueryRecord. */\n  desiredQueryIDs: v.array(v.string()),\n});\n\nexport type ClientRecord = v.Infer<typeof clientRecordSchema>;\n\nexport const baseQueryRecordSchema = v.object({\n  /** The client-specified ID used to identify this query. Typically a hash. */\n  id: v.string(),\n\n  /**\n   * The hash of the query after server-side transformations, which include:\n   *\n   * * Normalization (which may differ from what the client does)\n   * * Query \"expansion\" to include primary keys and query-execution-related columns\n   * * Authorization transforms\n   *\n   * Transformations depend on conditions that are independent of the db state version,\n   * such as server-side logic and authorization policies. As such, the version of a CVR\n   * version may need to be advanced independent of db state changes. This is done\n   * via the `minorVersion` counter of the CVRVersion object, which is used to account\n   * for both changes to the query set and changes to query transformations (which are\n   * effectively remove-old-query + add-new-query).\n   *\n   * Note that the transformed AST itself is **not** stored, as the result of the previous\n   * transformation is not useful in and of itself. If the current transformation results in\n   * a different hash than that of the transformation used for the last version of the CVR,\n   * it is simply handled by invalidating the existing rows, re-executed the query with\n   * the new transformation, and advancing the CVR's `minorVersion` and this query's\n   * `transformationVersion`.\n   *\n   * Note that the transformationHash is only stored when the query has reached the \"gotten\"\n   * state. If the query is in the \"desired\" but not yet \"gotten\" state, the field is absent.\n   */\n  transformationHash: v.string().optional(),\n\n  /**\n   * The CVR version corresponding to the `transformationHash`. This essentially tracks when\n   * this version of the query was effectively added to the CVR (as opposed to the\n   * `patchVersion`, which is simply when the client was notified that its query was added\n   * to the gotten set). Catchup of clients from old CVR versions require executing all\n   * queries with a newer `transformationVersion`.\n   */\n  transformationVersion: cvrVersionSchema.optional(),\n});\n\n/**\n * Internal queries track rows in the database for internal use, such as the\n * `lastMutationID`s in the `zero.clients` table. They participate in the standard\n * invalidation / update logic for row contents, but not in the desired/got or\n * size-based quota logic for client-requested queries.\n */\nexport const internalQueryRecordSchema = baseQueryRecordSchema.extend({\n  type: v.literal('internal'),\n  ast: astSchema,\n});\n\nexport type InternalQueryRecord = v.Infer<typeof internalQueryRecordSchema>;\n\nconst clientStateSchema = v.object({\n  /**\n   * The time at which the query was last inactivated. If this undefined or\n   * missing then the query is active.\n   *\n   * Desired queries are always active and have an undefined inactivatedAt.\n   */\n  inactivatedAt: ttlClockSchema.optional(),\n\n  /**\n   * TTL, time to live in milliseconds. If the query is not updated within this\n   * time. The time to live is the time after it has become inactive. Negative\n   * values are treated as `'forever'`.\n   *\n   * We do clamp this to a maximum of 10 minutes, so that queries do not\n   * live for a very long time in the CVR.\n   */\n  ttl: v.number(),\n\n  /**\n   * The version at which the client state changed (i.e. individual `patchVersion`s).\n   */\n  version: cvrVersionSchema,\n});\n\nconst externalQueryRecordSchema = baseQueryRecordSchema.extend({\n  /**\n   * The client state for this query, which includes the inactivatedAt, ttl and\n   * version. The client state is stored in a record with the client ID as the\n   * key.\n   */\n  clientState: v.record(clientStateSchema),\n\n  // For queries, the `patchVersion` indicates when query was added to the got set,\n  // and is absent if not yet gotten.\n  patchVersion: cvrVersionSchema.optional(),\n});\n\nexport const clientQueryRecordSchema = externalQueryRecordSchema.extend({\n  type: v.literal('client'),\n\n  /** The original AST as supplied by the client. */\n  ast: astSchema,\n});\n\nexport type ClientQueryRecord = v.Infer<typeof clientQueryRecordSchema>;\n\nexport const customQueryRecordSchema = externalQueryRecordSchema.extend({\n  type: v.literal('custom'),\n  name: v.string(),\n  args: v.readonly(v.array(jsonSchema)),\n});\n\nexport type CustomQueryRecord = v.Infer<typeof customQueryRecordSchema>;\n\nexport const queryRecordSchema = v.union(\n  clientQueryRecordSchema,\n  customQueryRecordSchema,\n  internalQueryRecordSchema,\n);\n\nexport type QueryRecord = v.Infer<typeof queryRecordSchema>;\n\nexport const rowIDSchema = v.object({\n  schema: v.string(),\n  table: v.string(),\n  rowKey: v.record(jsonValueSchema),\n});\n\nexport type RowID = v.Infer<typeof rowIDSchema>;\n\nexport const rowRecordSchema = cvrRecordSchema.extend({\n  id: rowIDSchema,\n  rowVersion: v.string(), // '_0_version' of the row\n  // query hashes => refCount, or `null` for a row that was removed from the\n  // view (i.e. tombstone).\n  refCounts: v.record(v.number()).nullable(),\n});\n\nexport type RowRecord = v.Infer<typeof rowRecordSchema>;\n\nexport const patchSchema = v.object({\n  type: v.literalUnion('row', 'query'),\n  op: v.literalUnion('put', 'del'),\n});\n\nexport const putRowPatchSchema = patchSchema.extend({\n  type: v.literal('row'),\n  op: v.literal('put'),\n  id: rowIDSchema,\n  rowVersion: v.string(), // '_0_version' of the row\n});\n\nexport type PutRowPatch = v.Infer<typeof putRowPatchSchema>;\n\nexport const delRowPatchSchema = patchSchema.extend({\n  type: v.literal('row'),\n  op: v.literal('del'),\n  id: rowIDSchema,\n});\n\nexport type DelRowPatch = v.Infer<typeof delRowPatchSchema>;\n\nexport const rowPatchSchema = v.union(putRowPatchSchema, delRowPatchSchema);\n\nexport type RowPatch = v.Infer<typeof rowPatchSchema>;\n\nexport const queryPatchSchema = patchSchema.extend({\n  type: v.literal('query'),\n  id: v.string(),\n  clientID: v.string().optional(), // defined for \"desired\", undefined for \"got\"\n});\n\nexport type QueryPatch = v.Infer<typeof queryPatchSchema>;\n\nexport type PutQueryPatch = QueryPatch & {op: 'put'};\nexport type DelQueryPatch = QueryPatch & {op: 'del'};\n\nexport const metadataPatchSchema = queryPatchSchema;\n\nexport type MetadataPatch = v.Infer<typeof metadataPatchSchema>;\n\nexport function versionString(v: CVRVersion) {\n  // The separator (e.g. \":\") needs to be lexicographically greater than the\n  // storage key path separator (e.g. \"/\") so that \"01/row-hash\" is less than \"01:01/row-hash\".\n  // In particular, the traditional separator for major.minor versions (\".\") does not\n  // satisfy this quality.\n  return v.configVersion\n    ? `${v.stateVersion}:${versionToLexi(v.configVersion)}`\n    : v.stateVersion;\n}\n\nexport function versionFromString(str: string): CVRVersion {\n  const parts = str.split(':');\n  const stateVersion = parts[0];\n  switch (parts.length) {\n    case 1: {\n      stateVersionFromString(stateVersion); // Purely for validation.\n      return {stateVersion};\n    }\n    case 2: {\n      const configVersion = versionFromLexi(parts[1]);\n      if (configVersion > BigInt(Number.MAX_SAFE_INTEGER)) {\n        throw new Error(`minorVersion ${parts[1]} exceeds max safe integer`);\n      }\n      return {stateVersion, configVersion: Number(configVersion)};\n    }\n    default:\n      throw new TypeError(`Invalid version string ${str}`);\n  }\n}\n\nexport function queryRecordToQueryRow(\n  clientGroupID: string,\n  query: QueryRecord,\n  rowSetSignature: string | null,\n): QueriesRow {\n  switch (query.type) {\n    case 'internal':\n      return {\n        clientGroupID,\n        queryHash: query.id,\n        clientAST: query.ast,\n        queryName: null,\n        queryArgs: null,\n        patchVersion: null,\n        transformationHash: query.transformationHash ?? null,\n        transformationVersion: maybeVersionString(query.transformationVersion),\n        internal: true,\n        deleted: false, // put vs del \"got\" query\n        rowSetSignature,\n      };\n    case 'client':\n      return {\n        clientGroupID,\n        queryHash: query.id,\n        clientAST: query.ast,\n        queryName: null,\n        queryArgs: null,\n        patchVersion: maybeVersionString(query.patchVersion),\n        transformationHash: query.transformationHash ?? null,\n        transformationVersion: maybeVersionString(query.transformationVersion),\n        internal: null,\n        deleted: false, // put vs del \"got\" query\n        rowSetSignature,\n      };\n    case 'custom':\n      return {\n        clientGroupID,\n        queryHash: query.id,\n        clientAST: null,\n        queryName: query.name,\n        queryArgs: query.args,\n        patchVersion: maybeVersionString(query.patchVersion),\n        transformationHash: query.transformationHash ?? null,\n        transformationVersion: maybeVersionString(query.transformationVersion),\n        internal: null,\n        deleted: false, // put vs del \"got\" query\n        rowSetSignature,\n      };\n  }\n}\n\nexport const maybeVersionString = (v: CVRVersion | undefined) =>\n  v ? versionString(v) : null;\n"],"mappings":"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"}

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The default maximum number of entries retained by a {@link SnapshotRowCache}.
+ *
+ * Each entry is a raw SQLite row (or the list of rows conflicting with
+ * a row on its unique keys) read while computing a snapshot diff. A
+ * replicated transaction of N rows produces up to 2N entries (the new value
+ * and the previous value(s) of each row), so the cache should be large enough
+ * to hold the largest transactions that are commonly replicated in order for
+ * all of the client groups on a worker to share the reads.
+ */
+export declare const DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES = 50000;
+/**
+ * How a statement's results are read: a single row (`Statement.get()`) or
+ * all rows (`Statement.all()`).
+ */
+export type ReadMode = 'get' | 'all';
+/**
+ * The maximum number of distinct SQL statements interned by a
+ * {@link SnapshotRowCache} before it is cleared. There is one per table and
+ * lookup shape, so this is only reached after many schema changes.
+ */
+export declare const MAX_INTERNED_STATEMENTS = 10000;
+/**
+ * A worker-wide, bounded cache of the rows that a `Snapshotter` reads from
+ * replica snapshots when computing the diff between two versions of the
+ * replica.
+ *
+ * Every client group (i.e. view-syncer) on a sync worker computes its own
+ * diff from the shared `_zero.changeLog2`, and each change in the diff costs
+ * two SQLite reads: the new value of the row (from the `curr` snapshot) and
+ * the previous value(s) that it replaces (from the `prev` snapshot). The
+ * reads for a given change are identical for every client group that
+ * traverses it, so a replicated transaction of N rows costs N × 2 × (client
+ * groups) reads per worker, most of which are redundant. This cache lets the
+ * client groups on a worker share those reads.
+ *
+ * ### Keys
+ *
+ * Entries are keyed by the exact SQL statement and arguments of the read
+ * (which encodes the table, the selected columns and the lookup keys), plus
+ * a `tag` supplied by the caller that pins the result to a version of the
+ * replica:
+ *
+ * - The new value of a row is the row as of the `stateVersion` recorded in
+ *   its change log entry (its `_0_version` is asserted to equal that
+ *   version), and is tagged with that `stateVersion`. It is thus shareable
+ *   by all client groups regardless of the snapshots they are advancing
+ *   between.
+ * - Previous values are read from the `prev` snapshot at its version, and
+ *   are tagged with that version (and, when the result can depend on the
+ *   changes applied to the snapshot before the read, the `curr` version
+ *   as well). See `Diff` in `snapshotter.ts` for the details.
+ *
+ * Because every key includes the version(s) that the result depends on,
+ * entries never go stale and are never invalidated; they are only evicted.
+ *
+ * ### Eviction
+ *
+ * The cache is bounded by entry count and evicts in insertion (FIFO) order
+ * rather than by recency. Diffs are traversed in change log order by every
+ * client group, so the entries that will not be needed again are those that
+ * were inserted the earliest (all groups have moved past them), while the
+ * most recently inserted entries are the ones that the trailing groups have
+ * yet to reach. Refreshing an entry on a hit would evict exactly the wrong
+ * entries when a trailing group catches up.
+ *
+ * ### Sharing
+ *
+ * Cached values are shared by reference across client groups and must
+ * therefore never be mutated by callers.
+ */
+export declare class SnapshotRowCache {
+    #private;
+    constructor(maxEntries?: number);
+    get size(): number;
+    get maxEntries(): number;
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+    /**
+     * Returns the cached result of the read identified by `tag`, `sql`, `mode`
+     * and `args`, or performs the read via `read()`, caching and returning its
+     * result. `undefined` results (i.e. a missing row) are not cached.
+     *
+     * `mode` is part of the key because the same statement can be read both
+     * ways: for a table whose only unique key is its primary key, `getRow()`
+     * and `getRows()` produce identical SQL, args and tags, but the former
+     * caches a row and the latter an array of rows.
+     */
+    getOrRead<T>(tag: string, sql: string, mode: ReadMode, args: unknown[], read: () => T): T;
+    clear(): void;
+}
+//# sourceMappingURL=snapshot-row-cache.d.ts.map

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-row-cache.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/snapshot-row-cache.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,eAAO,MAAM,sCAAsC,QAAS,CAAC;AAwB7D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAK9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,gBAAgB;;IAmB3B,YAAY,UAAU,SAAyC,EAE9D;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,KAAK,IAAI;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAEpD;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EACT,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,MAAM,CAAC,GACZ,CAAC,CAoBH;IAED,KAAK,IAAI,IAAI,CAIZ;CAsBF"}

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.js

@@ -0,0 +1,155 @@
+import { getOrInsert } from "../../../../shared/src/map.js";
+import { must } from "../../../../shared/src/must.js";
+import { stringify } from "../../../../shared/src/bigint-json.js";
+import { getOrCreateCounter } from "../../observability/metrics.js";
+import { RingBuffer } from "../../../../shared/src/ring-buffer.js";
+//#region ../zero-cache/src/services/view-syncer/snapshot-row-cache.ts
+/**
+* The default maximum number of entries retained by a {@link SnapshotRowCache}.
+*
+* Each entry is a raw SQLite row (or the list of rows conflicting with
+* a row on its unique keys) read while computing a snapshot diff. A
+* replicated transaction of N rows produces up to 2N entries (the new value
+* and the previous value(s) of each row), so the cache should be large enough
+* to hold the largest transactions that are commonly replicated in order for
+* all of the client groups on a worker to share the reads.
+*/
+var DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES = 5e4;
+/**
+* Serializes a lookup key value (i.e. a SQLite-bound parameter). Numbers and
+* bigints serialize identically, as row keys parsed from the change log are
+* JSON numbers whereas the values read from SQLite are bigints; both address
+* the same row. Strings are prefixed to distinguish them from numbers.
+*/
+function serialize(v) {
+	switch (typeof v) {
+		case "string": return "s" + v;
+		case "number":
+		case "bigint": return String(v);
+		case "boolean": return v ? "true" : "false";
+		case "object": return v === null ? "null" : "o" + stringify(v);
+		default: return "u" + String(v);
+	}
+}
+var HIT = { result: "hit" };
+var MISS = { result: "miss" };
+/**
+* A worker-wide, bounded cache of the rows that a `Snapshotter` reads from
+* replica snapshots when computing the diff between two versions of the
+* replica.
+*
+* Every client group (i.e. view-syncer) on a sync worker computes its own
+* diff from the shared `_zero.changeLog2`, and each change in the diff costs
+* two SQLite reads: the new value of the row (from the `curr` snapshot) and
+* the previous value(s) that it replaces (from the `prev` snapshot). The
+* reads for a given change are identical for every client group that
+* traverses it, so a replicated transaction of N rows costs N × 2 × (client
+* groups) reads per worker, most of which are redundant. This cache lets the
+* client groups on a worker share those reads.
+*
+* ### Keys
+*
+* Entries are keyed by the exact SQL statement and arguments of the read
+* (which encodes the table, the selected columns and the lookup keys), plus
+* a `tag` supplied by the caller that pins the result to a version of the
+* replica:
+*
+* - The new value of a row is the row as of the `stateVersion` recorded in
+*   its change log entry (its `_0_version` is asserted to equal that
+*   version), and is tagged with that `stateVersion`. It is thus shareable
+*   by all client groups regardless of the snapshots they are advancing
+*   between.
+* - Previous values are read from the `prev` snapshot at its version, and
+*   are tagged with that version (and, when the result can depend on the
+*   changes applied to the snapshot before the read, the `curr` version
+*   as well). See `Diff` in `snapshotter.ts` for the details.
+*
+* Because every key includes the version(s) that the result depends on,
+* entries never go stale and are never invalidated; they are only evicted.
+*
+* ### Eviction
+*
+* The cache is bounded by entry count and evicts in insertion (FIFO) order
+* rather than by recency. Diffs are traversed in change log order by every
+* client group, so the entries that will not be needed again are those that
+* were inserted the earliest (all groups have moved past them), while the
+* most recently inserted entries are the ones that the trailing groups have
+* yet to reach. Refreshing an entry on a hit would evict exactly the wrong
+* entries when a trailing group catches up.
+*
+* ### Sharing
+*
+* Cached values are shared by reference across client groups and must
+* therefore never be mutated by callers.
+*/
+var SnapshotRowCache = class {
+	#maxEntries;
+	#entries = /* @__PURE__ */ new Map();
+	#keys = new RingBuffer();
+	#sqlIDs = /* @__PURE__ */ new Map();
+	#reads = getOrCreateCounter("sync", "ivm.snapshot-row-reads", "Row reads performed while computing snapshot diffs for IVM, labeled by whether the read was served by the worker-wide snapshot row cache.");
+	#hits = 0;
+	#misses = 0;
+	constructor(maxEntries = DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES) {
+		this.#maxEntries = Math.max(0, maxEntries);
+	}
+	get size() {
+		return this.#entries.size;
+	}
+	get maxEntries() {
+		return this.#maxEntries;
+	}
+	stats() {
+		return {
+			hits: this.#hits,
+			misses: this.#misses,
+			size: this.#entries.size
+		};
+	}
+	/**
+	* Returns the cached result of the read identified by `tag`, `sql`, `mode`
+	* and `args`, or performs the read via `read()`, caching and returning its
+	* result. `undefined` results (i.e. a missing row) are not cached.
+	*
+	* `mode` is part of the key because the same statement can be read both
+	* ways: for a table whose only unique key is its primary key, `getRow()`
+	* and `getRows()` produce identical SQL, args and tags, but the former
+	* caches a row and the latter an array of rows.
+	*/
+	getOrRead(tag, sql, mode, args, read) {
+		const key = this.#key(tag, sql, mode, args);
+		const cached = this.#entries.get(key);
+		if (cached !== void 0) {
+			this.#hits++;
+			this.#reads.add(1, HIT);
+			return cached;
+		}
+		this.#misses++;
+		this.#reads.add(1, MISS);
+		const value = read();
+		if (value !== void 0 && this.#maxEntries > 0) {
+			this.#entries.set(key, value);
+			this.#keys.push(key);
+			if (this.#keys.size > this.#maxEntries) this.#entries.delete(must(this.#keys.shift()));
+		}
+		return value;
+	}
+	clear() {
+		this.#entries.clear();
+		this.#keys.clear();
+		this.#sqlIDs.clear();
+	}
+	#key(tag, sql, mode, args) {
+		if (this.#sqlIDs.size >= 1e4 && !this.#sqlIDs.has(sql)) this.clear();
+		let key = `${tag}\0${mode}${getOrInsert(this.#sqlIDs, sql, this.#sqlIDs.size)}`;
+		for (const arg of args) {
+			const serialized = serialize(arg);
+			key += `\0${serialized.length}:${serialized}`;
+		}
+		return key;
+	}
+};
+//#endregion
+export { SnapshotRowCache };
+
+//# sourceMappingURL=snapshot-row-cache.js.map

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-row-cache.js","names":["#maxEntries","#entries","#keys","#sqlIDs","#reads","#hits","#misses","#key"],"sources":["../../../../../../zero-cache/src/services/view-syncer/snapshot-row-cache.ts"],"sourcesContent":["import {stringify} from '../../../../shared/src/bigint-json.ts';\nimport {getOrInsert} from '../../../../shared/src/map.ts';\nimport {must} from '../../../../shared/src/must.ts';\nimport {RingBuffer} from '../../../../shared/src/ring-buffer.ts';\nimport {getOrCreateCounter} from '../../observability/metrics.ts';\n\n/**\n * The default maximum number of entries retained by a {@link SnapshotRowCache}.\n *\n * Each entry is a raw SQLite row (or the list of rows conflicting with\n * a row on its unique keys) read while computing a snapshot diff. A\n * replicated transaction of N rows produces up to 2N entries (the new value\n * and the previous value(s) of each row), so the cache should be large enough\n * to hold the largest transactions that are commonly replicated in order for\n * all of the client groups on a worker to share the reads.\n */\nexport const DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES = 50_000;\n\n/**\n * Serializes a lookup key value (i.e. a SQLite-bound parameter). Numbers and\n * bigints serialize identically, as row keys parsed from the change log are\n * JSON numbers whereas the values read from SQLite are bigints; both address\n * the same row. Strings are prefixed to distinguish them from numbers.\n */\nfunction serialize(v: unknown): string {\n  switch (typeof v) {\n    case 'string':\n      return 's' + v;\n    case 'number':\n    case 'bigint':\n      return String(v);\n    case 'boolean':\n      return v ? 'true' : 'false';\n    case 'object':\n      return v === null ? 'null' : 'o' + stringify(v);\n    default:\n      return 'u' + String(v);\n  }\n}\n\n/**\n * How a statement's results are read: a single row (`Statement.get()`) or\n * all rows (`Statement.all()`).\n */\nexport type ReadMode = 'get' | 'all';\n\n/**\n * The maximum number of distinct SQL statements interned by a\n * {@link SnapshotRowCache} before it is cleared. There is one per table and\n * lookup shape, so this is only reached after many schema changes.\n */\nexport const MAX_INTERNED_STATEMENTS = 10_000;\n\nconst HIT = {result: 'hit'} as const;\nconst MISS = {result: 'miss'} as const;\n\n/**\n * A worker-wide, bounded cache of the rows that a `Snapshotter` reads from\n * replica snapshots when computing the diff between two versions of the\n * replica.\n *\n * Every client group (i.e. view-syncer) on a sync worker computes its own\n * diff from the shared `_zero.changeLog2`, and each change in the diff costs\n * two SQLite reads: the new value of the row (from the `curr` snapshot) and\n * the previous value(s) that it replaces (from the `prev` snapshot). The\n * reads for a given change are identical for every client group that\n * traverses it, so a replicated transaction of N rows costs N × 2 × (client\n * groups) reads per worker, most of which are redundant. This cache lets the\n * client groups on a worker share those reads.\n *\n * ### Keys\n *\n * Entries are keyed by the exact SQL statement and arguments of the read\n * (which encodes the table, the selected columns and the lookup keys), plus\n * a `tag` supplied by the caller that pins the result to a version of the\n * replica:\n *\n * - The new value of a row is the row as of the `stateVersion` recorded in\n *   its change log entry (its `_0_version` is asserted to equal that\n *   version), and is tagged with that `stateVersion`. It is thus shareable\n *   by all client groups regardless of the snapshots they are advancing\n *   between.\n * - Previous values are read from the `prev` snapshot at its version, and\n *   are tagged with that version (and, when the result can depend on the\n *   changes applied to the snapshot before the read, the `curr` version\n *   as well). See `Diff` in `snapshotter.ts` for the details.\n *\n * Because every key includes the version(s) that the result depends on,\n * entries never go stale and are never invalidated; they are only evicted.\n *\n * ### Eviction\n *\n * The cache is bounded by entry count and evicts in insertion (FIFO) order\n * rather than by recency. Diffs are traversed in change log order by every\n * client group, so the entries that will not be needed again are those that\n * were inserted the earliest (all groups have moved past them), while the\n * most recently inserted entries are the ones that the trailing groups have\n * yet to reach. Refreshing an entry on a hit would evict exactly the wrong\n * entries when a trailing group catches up.\n *\n * ### Sharing\n *\n * Cached values are shared by reference across client groups and must\n * therefore never be mutated by callers.\n */\nexport class SnapshotRowCache {\n  readonly #maxEntries: number;\n  readonly #entries = new Map<string, unknown>();\n  // The keys of #entries in insertion order, so that the oldest can be\n  // evicted in O(1). (Finding the oldest key with a fresh Map iterator\n  // instead costs O(evictions) per insert, as V8 leaves deleted entries in\n  // the table until it is compacted and every new iterator walks over them.)\n  readonly #keys = new RingBuffer<string>();\n  // Interns the SQL text of each distinct read so that entry keys\n  // do not repeat the (long) column list of every statement.\n  readonly #sqlIDs = new Map<string, number>();\n  readonly #reads = getOrCreateCounter(\n    'sync',\n    'ivm.snapshot-row-reads',\n    'Row reads performed while computing snapshot diffs for IVM, labeled by whether the read was served by the worker-wide snapshot row cache.',\n  );\n  #hits = 0;\n  #misses = 0;\n\n  constructor(maxEntries = DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES) {\n    this.#maxEntries = Math.max(0, maxEntries);\n  }\n\n  get size(): number {\n    return this.#entries.size;\n  }\n\n  get maxEntries(): number {\n    return this.#maxEntries;\n  }\n\n  stats(): {hits: number; misses: number; size: number} {\n    return {hits: this.#hits, misses: this.#misses, size: this.#entries.size};\n  }\n\n  /**\n   * Returns the cached result of the read identified by `tag`, `sql`, `mode`\n   * and `args`, or performs the read via `read()`, caching and returning its\n   * result. `undefined` results (i.e. a missing row) are not cached.\n   *\n   * `mode` is part of the key because the same statement can be read both\n   * ways: for a table whose only unique key is its primary key, `getRow()`\n   * and `getRows()` produce identical SQL, args and tags, but the former\n   * caches a row and the latter an array of rows.\n   */\n  getOrRead<T>(\n    tag: string,\n    sql: string,\n    mode: ReadMode,\n    args: unknown[],\n    read: () => T,\n  ): T {\n    const key = this.#key(tag, sql, mode, args);\n    const cached = this.#entries.get(key);\n    if (cached !== undefined) {\n      this.#hits++;\n      this.#reads.add(1, HIT);\n      return cached as T;\n    }\n    this.#misses++;\n    this.#reads.add(1, MISS);\n    const value = read();\n    if (value !== undefined && this.#maxEntries > 0) {\n      // `key` is not in #entries (this is a miss), so it is always added.\n      this.#entries.set(key, value);\n      this.#keys.push(key);\n      if (this.#keys.size > this.#maxEntries) {\n        this.#entries.delete(must(this.#keys.shift()));\n      }\n    }\n    return value;\n  }\n\n  clear(): void {\n    this.#entries.clear();\n    this.#keys.clear();\n    this.#sqlIDs.clear();\n  }\n\n  #key(tag: string, sql: string, mode: ReadMode, args: unknown[]): string {\n    if (\n      this.#sqlIDs.size >= MAX_INTERNED_STATEMENTS &&\n      !this.#sqlIDs.has(sql)\n    ) {\n      // Statements are only added (e.g. when schema changes produce new\n      // column lists), so bound them by starting over. The entries refer to\n      // statements by ID and are cleared with them.\n      this.clear();\n    }\n    const sqlID = getOrInsert(this.#sqlIDs, sql, this.#sqlIDs.size);\n    let key = `${tag}\\0${mode}${sqlID}`;\n    // Include each value's length so separators inside string values cannot\n    // make different argument arrays produce the same key.\n    for (const arg of args) {\n      const serialized = serialize(arg);\n      key += `\\0${serialized.length}:${serialized}`;\n    }\n    return key;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAa,yCAAyC;;;;;;;AAQtD,SAAS,UAAU,GAAoB;CACrC,QAAQ,OAAO,GAAf;EACE,KAAK,UACH,OAAO,MAAM;EACf,KAAK;EACL,KAAK,UACH,OAAO,OAAO,CAAC;EACjB,KAAK,WACH,OAAO,IAAI,SAAS;EACtB,KAAK,UACH,OAAO,MAAM,OAAO,SAAS,MAAM,UAAU,CAAC;EAChD,SACE,OAAO,MAAM,OAAO,CAAC;CACzB;AACF;AAeA,IAAM,MAAM,EAAC,QAAQ,MAAK;AAC1B,IAAM,OAAO,EAAC,QAAQ,OAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmD5B,IAAa,mBAAb,MAA8B;CAC5B;CACA,2BAAoB,IAAI,IAAqB;CAK7C,QAAiB,IAAI,WAAmB;CAGxC,0BAAmB,IAAI,IAAoB;CAC3C,SAAkB,mBAChB,QACA,0BACA,2IACF;CACA,QAAQ;CACR,UAAU;CAEV,YAAY,aAAa,wCAAwC;EAC/D,KAAKA,cAAc,KAAK,IAAI,GAAG,UAAU;CAC3C;CAEA,IAAI,OAAe;EACjB,OAAO,KAAKC,SAAS;CACvB;CAEA,IAAI,aAAqB;EACvB,OAAO,KAAKD;CACd;CAEA,QAAsD;EACpD,OAAO;GAAC,MAAM,KAAKK;GAAO,QAAQ,KAAKC;GAAS,MAAM,KAAKL,SAAS;EAAI;CAC1E;;;;;;;;;;;CAYA,UACE,KACA,KACA,MACA,MACA,MACG;EACH,MAAM,MAAM,KAAKM,KAAK,KAAK,KAAK,MAAM,IAAI;EAC1C,MAAM,SAAS,KAAKN,SAAS,IAAI,GAAG;EACpC,IAAI,WAAW,KAAA,GAAW;GACxB,KAAKI;GACL,KAAKD,OAAO,IAAI,GAAG,GAAG;GACtB,OAAO;EACT;EACA,KAAKE;EACL,KAAKF,OAAO,IAAI,GAAG,IAAI;EACvB,MAAM,QAAQ,KAAK;EACnB,IAAI,UAAU,KAAA,KAAa,KAAKJ,cAAc,GAAG;GAE/C,KAAKC,SAAS,IAAI,KAAK,KAAK;GAC5B,KAAKC,MAAM,KAAK,GAAG;GACnB,IAAI,KAAKA,MAAM,OAAO,KAAKF,aACzB,KAAKC,SAAS,OAAO,KAAK,KAAKC,MAAM,MAAM,CAAC,CAAC;EAEjD;EACA,OAAO;CACT;CAEA,QAAc;EACZ,KAAKD,SAAS,MAAM;EACpB,KAAKC,MAAM,MAAM;EACjB,KAAKC,QAAQ,MAAM;CACrB;CAEA,KAAK,KAAa,KAAa,MAAgB,MAAyB;EACtE,IACE,KAAKA,QAAQ,QAAA,OACb,CAAC,KAAKA,QAAQ,IAAI,GAAG,GAKrB,KAAK,MAAM;EAGb,IAAI,MAAM,GAAG,IAAI,IAAI,OADP,YAAY,KAAKA,SAAS,KAAK,KAAKA,QAAQ,IAC9B;EAG5B,KAAK,MAAM,OAAO,MAAM;GACtB,MAAM,aAAa,UAAU,GAAG;GAChC,OAAO,KAAK,WAAW,OAAO,GAAG;EACnC;EACA,OAAO;CACT;AACF"}