@atscript/db-mongo 0.1.131 → 0.1.133

package/dist/agg.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_filter = require("./mongo-filter-z_hLPMyv.cjs");
+const require_mongo_filter = require("./mongo-filter-Bf5rWV4P.cjs");
 let _atscript_db_agg = require("@atscript/db/agg");
+let _uniqu_core = require("@uniqu/core");
 //#region src/agg.ts
 /** Simple accumulators that map directly to `{ $<fn>: '$field' }`. */
 const SIMPLE_ACCUMULATORS = {
@@ -25,21 +26,94 @@ function toAccumulator(expr) {
 	}
 	throw new Error(`Unsupported aggregate function: ${expr.$fn}`);
 }
+const DAY_MS = 864e5;
+const ISO_DATE = "%Y-%m-%d";
 /**
-* `$group` output field names (including `_id` sub-keys) may not contain `.`,
-* so a dotted `$groupBy` path (a JSON/nested descendant such as
-* `metadata.clicks`) is keyed positionally inside `_id` (`k0`, `k1`, …) and
-* projected back under its dotted path — `$project` accepts dotted output
-* keys and nests them, which is the row shape a dotted `$select` yields on
-* find (`{ metadata: { clicks } }`). Plain paths keep their own name.
+* Units whose first day `$dateToString` renders straight from the instant in
+* the zone: the local day, then the literal `01` for day-of-month / month.
 */
-function groupIdKey(field, index) {
-	return field.includes(".") ? `k${index}` : field;
+const LOCAL_DATE_FORMATS = {
+	day: ISO_DATE,
+	month: "%Y-%m-01",
+	year: "%Y-01-01"
+};
+/**
+* The first day of a quarter / week bucket as a NAIVE date (UTC midnight of
+* the local calendar date), from the local parts `$$p` (`$dateToParts` in
+* the zone). Pure calendar arithmetic: nothing converts local time back to an
+* instant, so a zone whose DST switch skips midnight cannot shift a label.
+*/
+function naiveFirstDay(b) {
+	if (b.unit === "quarter") return { $dateFromParts: {
+		year: "$$p.year",
+		month: { $subtract: ["$$p.month", { $mod: [{ $subtract: ["$$p.month", 1] }, 3] }] },
+		day: 1
+	} };
+	return { $let: {
+		vars: { n: { $dateFromParts: {
+			year: "$$p.year",
+			month: "$$p.month",
+			day: "$$p.day"
+		} } },
+		in: { $subtract: ["$$n", { $multiply: [{ $mod: [{ $add: [{ $subtract: [{ $isoDayOfWeek: "$$n" }, b.weekStartIso] }, 7] }, 7] }, DAY_MS] }] }
+	} };
+}
+/**
+* The `$group._id` expression of a calendar bucket: the ISO local date
+* `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+*
+* The only zone-aware step is instant → local date (`timezone` on
+* `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
+* deliberately not used — it returns the bucket start as an INSTANT, which
+* reintroduces the midnight-gap ambiguity.
+*
+* The source is an epoch-ms number of any BSON numeric type. The `$cond`
+* range guard `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)` labels an
+* out-of-range source `null`, like every other adapter, and also folds null,
+* missing and non-numeric sources (BSON orders null/missing below numbers and
+* strings/objects above them) into ONE null group — a bare field path would
+* group a missing source under `_id: {}`, apart from `_id: { k: null }`.
+*/
+function bucketExpression(b) {
+	const source = `$${b.field}`;
+	const date = { $toDate: { $toLong: source } };
+	const format = LOCAL_DATE_FORMATS[b.unit];
+	const label = format ? { $dateToString: {
+		date,
+		format,
+		timezone: b.tz
+	} } : { $let: {
+		vars: { p: { $dateToParts: {
+			date,
+			timezone: b.tz
+		} } },
+		in: { $dateToString: {
+			date: naiveFirstDay(b),
+			format: ISO_DATE
+		} }
+	} };
+	return { $cond: [
+		{ $and: [{ $gte: [source, _uniqu_core.BUCKET_MIN_INSTANT] }, { $lt: [source, _uniqu_core.BUCKET_MAX_INSTANT] }] },
+		label,
+		null
+	] };
 }
 /**
 * Builds the common prefix stages: [search] + $match + $group._id from groupBy
 * fields. Shared by both full aggregate and count pipelines.
-* `groupKeys` maps each `$groupBy` path to its `_id` sub-key.
+* `groupKeys` maps each `$groupBy` key (a field path or a calendar-bucket
+* alias) to its `_id` sub-key.
+*
+* Every key is stored positionally inside `_id` (`k0`, `k1`, …) — internal
+* names that never collide — and projected back under its own name:
+* `$group` output names may not contain `.`, while `$project` accepts dotted
+* output keys and nests them, which is the row shape a dotted `$select`
+* yields on find (`{ metadata: { clicks } }`).
+*
+* A field key is grouped as `{ $ifNull: ['$f', null] }` so a missing and a
+* null value form ONE null group (SQL semantics) that projects back as
+* `f: null` — a bare `'$f'` would split them into `_id: {}` and
+* `_id: { f: null }`. A bucket alias is grouped by {@link bucketExpression}.
 *
 * `searchStage` is the resolved text-search stage (classic `$text` `$match`, or
 * an Atlas `$search`). Both MUST be the pipeline's FIRST stage, hence its
@@ -52,10 +126,11 @@ function buildPrefix(query, searchStage) {
 	const pipeline = searchStage ? [searchStage, { $match: require_mongo_filter.buildMongoFilter(query.filter) }] : [{ $match: require_mongo_filter.buildMongoFilter(query.filter) }];
 	const groupId = {};
 	const groupKeys = [];
-	for (const [index, field] of groupBy.entries()) {
-		const idKey = groupIdKey(field, index);
-		groupId[idKey] = `$${field}`;
-		groupKeys.push([field, idKey]);
+	for (const [index, key] of groupBy.entries()) {
+		const idKey = `k${index}`;
+		const bucket = controls.$select?.bucketByAlias(key);
+		groupId[idKey] = bucket ? bucketExpression(bucket) : { $ifNull: [`$${key}`, null] };
+		groupKeys.push([key, idKey]);
 	}
 	return {
 		pipeline,
@@ -142,5 +217,6 @@ function buildCountPipeline(query, searchStage) {
 	return pipeline;
 }
 //#endregion
+exports.bucketExpression = bucketExpression;
 exports.buildAggregatePipeline = buildAggregatePipeline;
 exports.buildCountPipeline = buildCountPipeline;

package/dist/agg.d.cts

@@ -1,7 +1,24 @@
-import { DbQuery } from "@atscript/db";
+import { DbQuery, TResolvedBucket } from "@atscript/db";
 import { Document } from "mongodb";
 
 //#region src/agg.d.ts
+/**
+ * The `$group._id` expression of a calendar bucket: the ISO local date
+ * `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+ *
+ * The only zone-aware step is instant → local date (`timezone` on
+ * `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
+ * deliberately not used — it returns the bucket start as an INSTANT, which
+ * reintroduces the midnight-gap ambiguity.
+ *
+ * The source is an epoch-ms number of any BSON numeric type. The `$cond`
+ * range guard `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)` labels an
+ * out-of-range source `null`, like every other adapter, and also folds null,
+ * missing and non-numeric sources (BSON orders null/missing below numbers and
+ * strings/objects above them) into ONE null group — a bare field path would
+ * group a missing source under `_id: {}`, apart from `_id: { k: null }`.
+ */
+declare function bucketExpression(b: TResolvedBucket): Document;
 /**
  * Builds a full MongoDB aggregation pipeline for GROUP BY queries.
  *
@@ -27,4 +44,4 @@ declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document):
  */
 declare function buildCountPipeline(query: DbQuery, searchStage?: Document): Document[];
 //#endregion
-export { buildAggregatePipeline, buildCountPipeline };
+export { bucketExpression, buildAggregatePipeline, buildCountPipeline };

package/dist/agg.d.mts

@@ -1,7 +1,24 @@
-import { DbQuery } from "@atscript/db";
+import { DbQuery, TResolvedBucket } from "@atscript/db";
 import { Document } from "mongodb";
 
 //#region src/agg.d.ts
+/**
+ * The `$group._id` expression of a calendar bucket: the ISO local date
+ * `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+ *
+ * The only zone-aware step is instant → local date (`timezone` on
+ * `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
+ * deliberately not used — it returns the bucket start as an INSTANT, which
+ * reintroduces the midnight-gap ambiguity.
+ *
+ * The source is an epoch-ms number of any BSON numeric type. The `$cond`
+ * range guard `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)` labels an
+ * out-of-range source `null`, like every other adapter, and also folds null,
+ * missing and non-numeric sources (BSON orders null/missing below numbers and
+ * strings/objects above them) into ONE null group — a bare field path would
+ * group a missing source under `_id: {}`, apart from `_id: { k: null }`.
+ */
+declare function bucketExpression(b: TResolvedBucket): Document;
 /**
  * Builds a full MongoDB aggregation pipeline for GROUP BY queries.
  *
@@ -27,4 +44,4 @@ declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document):
  */
 declare function buildCountPipeline(query: DbQuery, searchStage?: Document): Document[];
 //#endregion
-export { buildAggregatePipeline, buildCountPipeline };
+export { bucketExpression, buildAggregatePipeline, buildCountPipeline };

package/dist/agg.mjs

@@ -1,5 +1,6 @@
-import { t as buildMongoFilter } from "./mongo-filter-DceAGI-S.mjs";
+import { t as buildMongoFilter } from "./mongo-filter-CtyITmZM.mjs";
 import { resolveAlias } from "@atscript/db/agg";
+import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/agg.ts
 /** Simple accumulators that map directly to `{ $<fn>: '$field' }`. */
 const SIMPLE_ACCUMULATORS = {
@@ -24,21 +25,94 @@ function toAccumulator(expr) {
 	}
 	throw new Error(`Unsupported aggregate function: ${expr.$fn}`);
 }
+const DAY_MS = 864e5;
+const ISO_DATE = "%Y-%m-%d";
 /**
-* `$group` output field names (including `_id` sub-keys) may not contain `.`,
-* so a dotted `$groupBy` path (a JSON/nested descendant such as
-* `metadata.clicks`) is keyed positionally inside `_id` (`k0`, `k1`, …) and
-* projected back under its dotted path — `$project` accepts dotted output
-* keys and nests them, which is the row shape a dotted `$select` yields on
-* find (`{ metadata: { clicks } }`). Plain paths keep their own name.
+* Units whose first day `$dateToString` renders straight from the instant in
+* the zone: the local day, then the literal `01` for day-of-month / month.
 */
-function groupIdKey(field, index) {
-	return field.includes(".") ? `k${index}` : field;
+const LOCAL_DATE_FORMATS = {
+	day: ISO_DATE,
+	month: "%Y-%m-01",
+	year: "%Y-01-01"
+};
+/**
+* The first day of a quarter / week bucket as a NAIVE date (UTC midnight of
+* the local calendar date), from the local parts `$$p` (`$dateToParts` in
+* the zone). Pure calendar arithmetic: nothing converts local time back to an
+* instant, so a zone whose DST switch skips midnight cannot shift a label.
+*/
+function naiveFirstDay(b) {
+	if (b.unit === "quarter") return { $dateFromParts: {
+		year: "$$p.year",
+		month: { $subtract: ["$$p.month", { $mod: [{ $subtract: ["$$p.month", 1] }, 3] }] },
+		day: 1
+	} };
+	return { $let: {
+		vars: { n: { $dateFromParts: {
+			year: "$$p.year",
+			month: "$$p.month",
+			day: "$$p.day"
+		} } },
+		in: { $subtract: ["$$n", { $multiply: [{ $mod: [{ $add: [{ $subtract: [{ $isoDayOfWeek: "$$n" }, b.weekStartIso] }, 7] }, 7] }, DAY_MS] }] }
+	} };
+}
+/**
+* The `$group._id` expression of a calendar bucket: the ISO local date
+* `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+*
+* The only zone-aware step is instant → local date (`timezone` on
+* `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
+* deliberately not used — it returns the bucket start as an INSTANT, which
+* reintroduces the midnight-gap ambiguity.
+*
+* The source is an epoch-ms number of any BSON numeric type. The `$cond`
+* range guard `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)` labels an
+* out-of-range source `null`, like every other adapter, and also folds null,
+* missing and non-numeric sources (BSON orders null/missing below numbers and
+* strings/objects above them) into ONE null group — a bare field path would
+* group a missing source under `_id: {}`, apart from `_id: { k: null }`.
+*/
+function bucketExpression(b) {
+	const source = `$${b.field}`;
+	const date = { $toDate: { $toLong: source } };
+	const format = LOCAL_DATE_FORMATS[b.unit];
+	const label = format ? { $dateToString: {
+		date,
+		format,
+		timezone: b.tz
+	} } : { $let: {
+		vars: { p: { $dateToParts: {
+			date,
+			timezone: b.tz
+		} } },
+		in: { $dateToString: {
+			date: naiveFirstDay(b),
+			format: ISO_DATE
+		} }
+	} };
+	return { $cond: [
+		{ $and: [{ $gte: [source, BUCKET_MIN_INSTANT] }, { $lt: [source, BUCKET_MAX_INSTANT] }] },
+		label,
+		null
+	] };
 }
 /**
 * Builds the common prefix stages: [search] + $match + $group._id from groupBy
 * fields. Shared by both full aggregate and count pipelines.
-* `groupKeys` maps each `$groupBy` path to its `_id` sub-key.
+* `groupKeys` maps each `$groupBy` key (a field path or a calendar-bucket
+* alias) to its `_id` sub-key.
+*
+* Every key is stored positionally inside `_id` (`k0`, `k1`, …) — internal
+* names that never collide — and projected back under its own name:
+* `$group` output names may not contain `.`, while `$project` accepts dotted
+* output keys and nests them, which is the row shape a dotted `$select`
+* yields on find (`{ metadata: { clicks } }`).
+*
+* A field key is grouped as `{ $ifNull: ['$f', null] }` so a missing and a
+* null value form ONE null group (SQL semantics) that projects back as
+* `f: null` — a bare `'$f'` would split them into `_id: {}` and
+* `_id: { f: null }`. A bucket alias is grouped by {@link bucketExpression}.
 *
 * `searchStage` is the resolved text-search stage (classic `$text` `$match`, or
 * an Atlas `$search`). Both MUST be the pipeline's FIRST stage, hence its
@@ -51,10 +125,11 @@ function buildPrefix(query, searchStage) {
 	const pipeline = searchStage ? [searchStage, { $match: buildMongoFilter(query.filter) }] : [{ $match: buildMongoFilter(query.filter) }];
 	const groupId = {};
 	const groupKeys = [];
-	for (const [index, field] of groupBy.entries()) {
-		const idKey = groupIdKey(field, index);
-		groupId[idKey] = `$${field}`;
-		groupKeys.push([field, idKey]);
+	for (const [index, key] of groupBy.entries()) {
+		const idKey = `k${index}`;
+		const bucket = controls.$select?.bucketByAlias(key);
+		groupId[idKey] = bucket ? bucketExpression(bucket) : { $ifNull: [`$${key}`, null] };
+		groupKeys.push([key, idKey]);
 	}
 	return {
 		pipeline,
@@ -141,4 +216,4 @@ function buildCountPipeline(query, searchStage) {
 	return pipeline;
 }
 //#endregion
-export { buildAggregatePipeline, buildCountPipeline };
+export { bucketExpression, buildAggregatePipeline, buildCountPipeline };

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_filter = require("./mongo-filter-z_hLPMyv.cjs");
+const require_mongo_filter = require("./mongo-filter-Bf5rWV4P.cjs");
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
 let _atscript_db_agg = require("@atscript/db/agg");
@@ -33,19 +33,32 @@ function dedupeProjection(projection) {
 }
 //#endregion
 //#region src/lib/mongo-errors.ts
+/** Server code for an unrecognized `timezone` in a date expression (verified on MongoDB 7.0 and 8.0). */
+const UNKNOWN_TIME_ZONE = 40485;
 /**
-* Maps MongoDB projection-validation errors (31249, 31254) to `DbError("INVALID_QUERY")`
-* so moost-db's validation interceptor returns HTTP 400 instead of an opaque 500.
-* These codes always indicate malformed client `$select`, not a server fault.
+* Maps MongoDB server errors that describe the query, not a server fault:
+* - projection validation (31249, 31254) → `DbError("INVALID_QUERY")` (moost-db:
+*   400) — these codes always indicate a malformed client `$select`;
+* - an unrecognized time zone identifier (40485) → `BUCKET_TZ_UNAVAILABLE`
+*   (moost-db: 501). Only calendar buckets put a zone into a pipeline, and the
+*   core already accepted it as a canonical IANA name — so the server's
+*   bundled tz database lacking it is a store condition, never a silent NULL
+*   or UTC label.
 */
 async function wrapInvalidQuery(fn) {
 	try {
 		return await fn();
 	} catch (error) {
-		if (error instanceof mongodb.MongoServerError && (error.code === 31249 || error.code === 31254)) throw new _atscript_db.DbError("INVALID_QUERY", [{
-			path: "$select",
-			message: error.message
-		}]);
+		if (error instanceof mongodb.MongoServerError) {
+			if (error.code === 31249 || error.code === 31254) throw new _atscript_db.DbError("INVALID_QUERY", [{
+				path: "$select",
+				message: error.message
+			}]);
+			if (error.code === UNKNOWN_TIME_ZONE) {
+				const zone = /time zone identifier:\s*"([^"]*)"/.exec(error.message)?.[1];
+				throw (0, _atscript_db.bucketTimeZoneUnavailable)(zone ? `MongoDB does not recognize time zone "${zone}" — its time zone database may be outdated` : `MongoDB does not recognize a bucket time zone: ${error.message}`);
+			}
+		}
 		throw error;
 	}
 }
@@ -1750,6 +1763,10 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 	supportsNativePatch() {
 		return true;
 	}
+	/** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+	calendarBucketUnits() {
+		return _atscript_db.ALL_BUCKET_UNITS;
+	}
 	getValidatorPlugins() {
 		return [validateMongoIdPlugin];
 	}

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
 import { AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
 import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+import { BucketUnit } from "@uniqu/core";
 
 //#region src/lib/collection-patcher.d.ts
 /**
@@ -300,6 +301,8 @@ declare class MongoAdapter extends BaseDbAdapter {
   prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
   supportsNestedObjects(): boolean;
   supportsNativePatch(): boolean;
+  /** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   getValidatorPlugins(): ReturnType<BaseDbAdapter["getValidatorPlugins"]>;
   /**
    * Mongo can filter on JSON-stored fields natively — arrays via implicit

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
 import { AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
+import { BucketUnit } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 
 //#region src/lib/collection-patcher.d.ts
@@ -300,6 +301,8 @@ declare class MongoAdapter extends BaseDbAdapter {
   prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
   supportsNestedObjects(): boolean;
   supportsNativePatch(): boolean;
+  /** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   getValidatorPlugins(): ReturnType<BaseDbAdapter["getValidatorPlugins"]>;
   /**
    * Mongo can filter on JSON-stored fields natively — arrays via implicit

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { t as buildMongoFilter } from "./mongo-filter-DceAGI-S.mjs";
-import { BaseDbAdapter, DbError, DbSpace, computeInsights, createFailureCollector, getDbFieldOp, getKeyProps, isAtscriptDbView, resolveDesignType } from "@atscript/db";
+import { t as buildMongoFilter } from "./mongo-filter-CtyITmZM.mjs";
+import { ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, computeInsights, createFailureCollector, getDbFieldOp, getKeyProps, isAtscriptDbView, resolveDesignType } from "@atscript/db";
 import { MongoClient, MongoServerError, ObjectId } from "mongodb";
 import { resolveAggregateSearch } from "@atscript/db/agg";
 //#region src/lib/path-utils.ts
@@ -32,19 +32,32 @@ function dedupeProjection(projection) {
 }
 //#endregion
 //#region src/lib/mongo-errors.ts
+/** Server code for an unrecognized `timezone` in a date expression (verified on MongoDB 7.0 and 8.0). */
+const UNKNOWN_TIME_ZONE = 40485;
 /**
-* Maps MongoDB projection-validation errors (31249, 31254) to `DbError("INVALID_QUERY")`
-* so moost-db's validation interceptor returns HTTP 400 instead of an opaque 500.
-* These codes always indicate malformed client `$select`, not a server fault.
+* Maps MongoDB server errors that describe the query, not a server fault:
+* - projection validation (31249, 31254) → `DbError("INVALID_QUERY")` (moost-db:
+*   400) — these codes always indicate a malformed client `$select`;
+* - an unrecognized time zone identifier (40485) → `BUCKET_TZ_UNAVAILABLE`
+*   (moost-db: 501). Only calendar buckets put a zone into a pipeline, and the
+*   core already accepted it as a canonical IANA name — so the server's
+*   bundled tz database lacking it is a store condition, never a silent NULL
+*   or UTC label.
 */
 async function wrapInvalidQuery(fn) {
 	try {
 		return await fn();
 	} catch (error) {
-		if (error instanceof MongoServerError && (error.code === 31249 || error.code === 31254)) throw new DbError("INVALID_QUERY", [{
-			path: "$select",
-			message: error.message
-		}]);
+		if (error instanceof MongoServerError) {
+			if (error.code === 31249 || error.code === 31254) throw new DbError("INVALID_QUERY", [{
+				path: "$select",
+				message: error.message
+			}]);
+			if (error.code === UNKNOWN_TIME_ZONE) {
+				const zone = /time zone identifier:\s*"([^"]*)"/.exec(error.message)?.[1];
+				throw bucketTimeZoneUnavailable(zone ? `MongoDB does not recognize time zone "${zone}" — its time zone database may be outdated` : `MongoDB does not recognize a bucket time zone: ${error.message}`);
+			}
+		}
 		throw error;
 	}
 }
@@ -1749,6 +1762,10 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	supportsNativePatch() {
 		return true;
 	}
+	/** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+	calendarBucketUnits() {
+		return ALL_BUCKET_UNITS;
+	}
 	getValidatorPlugins() {
 		return [validateMongoIdPlugin];
 	}

package/dist/{mongo-filter-z_hLPMyv.cjs → mongo-filter-Bf5rWV4P.cjs}

@@ -25,6 +25,7 @@ const EARTH_RADIUS_M = 6378100;
 const mongoVisitor = {
 	comparison(field, op, value) {
 		if (op === "$eq") return { [field]: value };
+		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
 		if (op === "$regex") {
 			const { pattern, flags } = parseRegexString(value);
 			return flags ? { [field]: {

package/dist/{mongo-filter-DceAGI-S.mjs → mongo-filter-CtyITmZM.mjs}

@@ -25,6 +25,7 @@ const EARTH_RADIUS_M = 6378100;
 const mongoVisitor = {
 	comparison(field, op, value) {
 		if (op === "$eq") return { [field]: value };
+		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
 		if (op === "$regex") {
 			const { pattern, flags } = parseRegexString(value);
 			return flags ? { [field]: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -48,6 +48,7 @@
   "devDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
+    "@uniqu/core": "^0.1.10",
     "mongodb": "^6.17.0",
     "mongodb-memory-server-core": "^10.0.0",
     "unplugin-atscript": "^0.1.92"
@@ -55,8 +56,9 @@
   "peerDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
+    "@uniqu/core": "^0.1.10",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.131"
+    "@atscript/db": "^0.1.133"
   },
   "scripts": {
     "postinstall": "asc -f dts",