monsqlize 3.4.0 → 3.5.1

package/CHANGELOG.md

@@ -1,18 +1,20 @@
 # CHANGELOG
 
-> Summary index — the 3.4.0 versioned details are in [changelogs/v3.4.0.md](./changelogs/v3.4.0.md). A versioned note does not establish npm publication; check the registry and immutable tag before deployment.
-> **Last updated**: 2026-10-27
+> Summary index — the 3.5.1 versioned details are in [changelogs/v3.5.1.md](./changelogs/v3.5.1.md). A versioned note does not establish npm publication; check the registry and immutable tag before deployment.
+> **Last updated**: 2026-10-28
 
 ---
 
 ## Unreleased
 
-The Search index lifecycle API is assigned to **3.4.0** ([versioned notes](./changelogs/v3.4.0.md)); the weekly-scan cache-key, health-check and lockfile security fixes are in [3.3.4](./changelogs/v3.3.4.md); the schema-dsl 3.0.5 upgrade is in [3.3.3](./changelogs/v3.3.3.md); the audited 3.3.2 repairs are in its [versioned notes](./changelogs/v3.3.2.md) and the [next-change staging log](https://github.com/devcodex-labs/monSQLize/blob/main/changelogs/unreleased.md). Untagged checkouts remain release candidates.
+README, docs-site share card and release tooling fixes are assigned to **3.5.1** ([versioned notes](./changelogs/v3.5.1.md)); GridFS buckets are in [3.5.0](./changelogs/v3.5.0.md); the Search index lifecycle API is in [3.4.0](./changelogs/v3.4.0.md); the weekly-scan cache-key, health-check and lockfile security fixes are in [3.3.4](./changelogs/v3.3.4.md); the schema-dsl 3.0.5 upgrade is in [3.3.3](./changelogs/v3.3.3.md); the audited 3.3.2 repairs are in its [versioned notes](./changelogs/v3.3.2.md) and the [next-change staging log](https://github.com/devcodex-labs/monSQLize/blob/main/changelogs/unreleased.md). Untagged checkouts remain release candidates.
 
 ## Version Overview
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v3.5.1](./changelogs/v3.5.1.md) | 2026-10-28 | Patch: README support wording and native-driver example, docs-site share card and locale meta; no runtime changes | [View](./changelogs/v3.5.1.md) |
+| [v3.5.0](./changelogs/v3.5.0.md) | 2026-10-27 | Minor: GridFS buckets with upload, download, ranges, ensureIndexes and phase-1 resumable upload | [View](./changelogs/v3.5.0.md) |
 | [v3.4.0](./changelogs/v3.4.0.md) | 2026-10-27 | Minor: Search index lifecycle API for Atlas Search and Vector Search | [View](./changelogs/v3.4.0.md) |
 | [v3.3.4](./changelogs/v3.3.4.md) | 2026-10-26 | Patch: cached-read keys under autoConvertObjectId, hung health-check pings, lockfile security patches | [View](./changelogs/v3.3.4.md) |
 | [v3.3.3](./changelogs/v3.3.3.md) | 2026-10-23 | Patch: pin schema-dsl 3.0.5 (dependency bug fixes only) | [View](./changelogs/v3.3.3.md) |

package/README.md

@@ -14,7 +14,7 @@ Upgrade and security: [Migration Guide](./MIGRATION.md) · [Private Vulnerabilit
 
 The npm `latest` dist-tag and GitHub Pages are the stable channel; `main` may contain the next release. Pages deployment accepts only a versioned Git tag whose package version is already present on npm, so unpublished APIs are not promoted as stable documentation. The Google site ownership verification file is copied separately from the workflow commit, with its source commit and content hash recorded in the deployment summary.
 
-This source tree targets **3.4.0**, a minor release that adds the Search index lifecycle API for Atlas Search and Vector Search (see the [3.4.0 notes](./changelogs/v3.4.0.md)); 3.3.4 fixed cached-read keys under `autoConvertObjectId`, hung health-check pings and lockfile security advisories. The 3.3.2 cache, Model, pagination and sync fixes, including cold-cache upgrades and checkpoint rollback limits, are described in the [3.3.2 notes](./changelogs/v3.3.2.md) and [migration guide](./MIGRATION.md). Read the upgrade guide in [English](https://github.com/devcodex-labs/monSQLize/blob/main/docs/en/upgrade-3.3.2.md) or [简体中文](https://github.com/devcodex-labs/monSQLize/blob/main/docs/zh/upgrade-3.3.2.md). Untagged checkouts remain release candidates; verify the immutable tag and requested registry version before deployment. Candidate preparation does not publish npm or update stable Pages.
+This source tree targets **3.5.1**, a documentation patch with no runtime changes (see the [3.5.1 notes](./changelogs/v3.5.1.md)); 3.5.0 added GridFS buckets on `msq.gridfs()` and `model.gridfs()`, and 3.4.0 added the Search index lifecycle API for Atlas Search and Vector Search. The 3.3.2 cache, Model, pagination and sync fixes, including cold-cache upgrades and checkpoint rollback limits, are described in the [3.3.2 notes](./changelogs/v3.3.2.md) and [migration guide](./MIGRATION.md). Read the upgrade guide in [English](https://github.com/devcodex-labs/monSQLize/blob/main/docs/en/upgrade-3.3.2.md) or [简体中文](https://github.com/devcodex-labs/monSQLize/blob/main/docs/zh/upgrade-3.3.2.md). Untagged checkouts remain release candidates; verify the immutable tag and requested registry version before deployment. Candidate preparation does not publish npm or update stable Pages.
 
 This development source is pinned to verified registry `schema-dsl@3.0.5`. The v3 package remains subject to the full release gate before an immutable tag and npm publication.
 
@@ -22,7 +22,7 @@ This development source is pinned to verified registry `schema-dsl@3.0.5`. The v
 npm install monsqlize
 ```
 
-MongoDB is the first complete adapter. MySQL and PostgreSQL adapters are planned as database-native runtime adapters, not as a transparent promise that every database already accepts the same query syntax.
+Database-native production runtime for MongoDB today, with MySQL and PostgreSQL adapters next. MongoDB is stable today; MySQL and PostgreSQL are planned as database-native adapters, not fake MongoDB dialects. The current official support scope is only MongoDB.
 
 ## Why monSQLize
 
@@ -38,13 +38,13 @@ monSQLize is not an ORM and it is not just a CRUD wrapper. It is a production da
 
 ## Adapter Status
 
-| Adapter | Current status | Public entry |
+| Adapter | Status | Public entry |
 |---|---|---|
-| MongoDB | Stable and fully implemented | `type: 'mongodb'`, `collection()`, `db()`, `use()`, `pool()` |
+| MongoDB | Stable | `type: 'mongodb'`, `collection()`, `db()`, `use()`, `pool()` |
 | MySQL | Planned / in development | Not part of the current npm runtime yet |
 | PostgreSQL | Planned / in development | Not part of the current npm runtime yet |
 
-The shared runtime direction is cache consistency, connection lifecycle, transaction helpers, model constraints, synchronization, and observability across adapters. Adapter-native query, transaction, and connection semantics will stay explicit.
+The current stable adapter is MongoDB. MySQL and PostgreSQL adapters are next: they are planned as database-native adapters under the same runtime contract (cache consistency, connection lifecycle, transaction helpers, model constraints, synchronization, and observability), not as fake MongoDB dialects. The current official support scope is only MongoDB.
 
 ## Runtime Consistency Contract
 
@@ -78,7 +78,7 @@ monSQLize is a good fit when you need:
 |---|---|
 | High-concurrency reads | Cache hot data and reduce repeated database work. |
 | MongoDB API compatibility today | Keep familiar MongoDB syntax while adding higher-level runtime helpers. |
-| A future multi-database runtime boundary | Prepare for MySQL/PostgreSQL adapters without turning SQL into fake MongoDB syntax. |
+| The next database adapters | MySQL and PostgreSQL are planned as database-native adapters, not fake MongoDB dialects. |
 | Multi-instance services | Use Redis invalidation and pool health checks to keep instances coordinated. |
 | Transaction-heavy flows | Use `withTransaction()` and transaction-aware helpers instead of hand-rolled lifecycle code. |
 | Model-level ergonomics | Add schema validation, hooks, populate, and custom methods only where needed. |
@@ -96,7 +96,7 @@ Use Node.js 18 or newer and provide a MongoDB connection URI. Optional Redis, SS
 
 ## Quick Start
 
-The current stable quick start uses the MongoDB adapter.
+The current stable quick start uses the MongoDB adapter. MySQL and PostgreSQL are planned next and are not part of this sample.
 
 ### CommonJS
 
@@ -170,6 +170,67 @@ Published entry points:
 
 The package root exports only the public package contract. Deep imports into historical `lib/**` files are not part of the v3 publishing surface.
 
+## Native driver vs monSQLize
+
+The same task in both styles: one page of active orders, newest `createdAt` first, with a cursor for the next page and a 60-second result cache.
+
+### MongoDB Node driver
+
+The query below is the official `mongodb` driver (`find` / `sort` / `limit`). The cursor token (`createdAt` ISO time, `|`, ObjectId hex), the `$or` range, and the in-process cache are application code. `JSON` does not preserve BSON types.
+
+```ts
+import { MongoClient, ObjectId, type Document } from 'mongodb';
+
+type Order = { status: string; createdAt: Date };
+const orders = new MongoClient('mongodb://localhost:27017').db('shop').collection<Order>('orders');
+const pageCache = new Map<string, string>();
+
+export async function listActiveOrders(cursor?: string | null, limit = 20) {
+  const cacheKey = `orders:active:${limit}:${cursor ?? ''}`;
+  const hit = pageCache.get(cacheKey);
+  if (hit) return JSON.parse(hit) as { items: Order[]; hasNext: boolean; endCursor: string | null };
+  const filter: Document = { status: 'active' };
+  if (cursor) {
+    const [iso, id] = cursor.split('|');
+    const createdAt = new Date(iso);
+    filter.$or = [{ createdAt: { $lt: createdAt } }, { createdAt, _id: { $lt: new ObjectId(id) } }];
+  }
+  const docs = await orders.find(filter).sort({ createdAt: -1, _id: -1 }).limit(limit + 1).toArray();
+  const items = docs.slice(0, limit);
+  const last = items.at(-1);
+  const page = { items, hasNext: docs.length > limit, endCursor: last ? `${last.createdAt.toISOString()}|${last._id.toHexString()}` : null };
+  pageCache.set(cacheKey, JSON.stringify(page));
+  return page;
+}
+```
+
+### monSQLize
+
+`findPage` takes one options object. `cache` is the page-result TTL in milliseconds. When `sort` omits `_id`, `findPage` adds `_id: 1`. Pass `page.pageInfo.endCursor` as `after` for the next page. Writes do not clear this cache unless you opt in (`cache.invalidate`, `autoInvalidate`, or `collection.invalidate('findPage')`). See [findPage](./docs/en/findPage.md).
+
+```ts
+import MonSQLize from 'monsqlize';
+
+const msq = new MonSQLize({
+  type: 'mongodb',
+  databaseName: 'shop',
+  config: { uri: 'mongodb://localhost:27017' },
+  cache: { maxEntries: 10_000, defaultTtl: 60_000 },
+});
+await msq.connect();
+
+export async function listActiveOrders(cursor?: string | null) {
+  const page = await msq.collection<{ createdAt: Date }>('orders').findPage({
+    query: { status: 'active' },
+    sort: { createdAt: -1 },
+    limit: 20,
+    after: cursor ?? undefined,
+    cache: 60_000,
+  });
+  return { items: page.items, hasNext: page.pageInfo.hasNext, endCursor: page.pageInfo.endCursor };
+}
+```
+
 ## Model Layer
 
 The Model layer is optional. Use it when you want schema validation, hooks, relations, populate, custom methods, timestamps, soft delete, or optimistic locking.
@@ -617,10 +678,9 @@ npm run test:real-env:private
 
 ## Roadmap
 
-- MongoDB remains the stable adapter and the current production runtime.
-- MySQL and PostgreSQL adapters will be introduced as database-native adapters under the same production runtime contract.
-- Adapter status will move from planned to alpha/stable only after runtime support, public types, examples, and verification coverage are present.
-- The project does not currently promise production-ready "one query syntax automatically adapts to every database" behavior.
+- MongoDB is stable today and remains the current production runtime. The current official support scope is only MongoDB.
+- MySQL and PostgreSQL adapters are next. They are planned as database-native adapters, not fake MongoDB dialects, and are not part of the current npm runtime yet.
+- A production-ready "one query syntax that automatically adapts to all databases" is not part of the current version.
 - Query analyzer improvements.
 - Automatic index suggestions.
 - Additional data-task observability and large-scope operational probes.

package/changelogs/v3.5.0.md

@@ -0,0 +1,23 @@
+# monSQLize v3.5.0
+
+> Release date: 2026-10-27
+> Publication authority: the immutable tag and npm registry. An untagged checkout is a release candidate; the date above does not establish registry availability.
+
+## Highlights
+
+Minor release. Adds GridFS buckets on `msq.gridfs()` and `model.gridfs()`. Existing APIs, defaults and dependency versions are unchanged. Node.js `>=18` remains the consumer runtime.
+
+## Added
+
+- GridFS buckets: upload, download, byte ranges, `getFile`, `findFiles`, delete/drop, and a formal `ensureIndexes` method. `contentType` is stored in `metadata.contentType` (compatible with MongoDB Driver 6.x and 7.x).
+- Phase-1 resumable upload: start, append chunks, finalize and abort. Upload sessions expire through a 7-day TTL index that does not cascade to already written chunks.
+- `writePathPolicy` gains a `gridfs` field and category. Under model-only with inherit, GridFS reads stay allowed and writes require `gridfs: 'allow'`; `drop` is a management operation. Violations stay `INVALID_OPERATION` with `reason: 'WRITE_PATH_POLICY'`. Matching receives the collection-style internal instance id (`iid`).
+- Six `GRIDFS_*` error codes. Driver failures from `getFile`, `findFiles`, `abortResumableUpload` and index creation map to `MONGODB_ERROR`, with the driver error kept as `cause`.
+
+## Budgets
+
+- Root CJS runtime budget rises to 874,000 bytes and ESM to 871,000 bytes; `gridfs()` stays synchronous, so the single-file build keeps GridFS in the main bundle. The CLI budget stays 50,000 bytes.
+
+## Upgrade and rollback
+
+No migration is required for existing APIs. GridFS methods are additive. Rollback to 3.4.0 removes the GridFS API and restores the previous bundle budgets; GridFS collections already written remain readable through the native driver.

package/changelogs/v3.5.1.md

@@ -0,0 +1,21 @@
+# monSQLize v3.5.1
+
+> Release date: 2026-10-28
+> Publication authority: the immutable tag and npm registry. An untagged checkout is a release candidate; the date above does not establish registry availability.
+
+## Highlights
+
+Patch release for documentation and release tooling. There are no runtime or library changes: public APIs, defaults, bundle output and dependency versions are the same as 3.5.0.
+
+## Documentation
+
+- The README now states that MongoDB is supported (stable) today, with MySQL and PostgreSQL adapters as the next step, matching the docs site. It adds a native-driver vs monSQLize example.
+- The docs site gains a 1200x630 `og:image` share card and `twitter:card=summary_large_image` / `twitter:image` meta. Page `description` meta now matches each page's language.
+
+## Release tooling
+
+- The release-candidate check treats HEAD as pushed when it is an ancestor of an origin branch, including after a newer commit becomes the tip. Shallow clones fetch and deepen history first. Local-only commits still fail.
+
+## Upgrade and rollback
+
+No migration is required. Rollback to 3.5.0 is safe and changes only the packaged README and changelog.

package/dist/cjs/cli/data-task.cjs

@@ -31,7 +31,7 @@ var import_node_url = require("node:url");
 // package.json
 var package_default = {
   name: "monsqlize",
-  version: "3.4.0",
+  version: "3.5.1",
   description: "TypeScript production data runtime layer for MongoDB today, with cache, transactions, pools, models, sync, and observability",
   type: "commonjs",
   main: "./dist/cjs/index.cjs",
@@ -52,6 +52,8 @@ var package_default = {
     "./package.json": "./package.json"
   },
   files: [
+    "changelogs/v3.5.1.md",
+    "changelogs/v3.5.0.md",
     "changelogs/v3.4.0.md",
     "changelogs/v3.3.3.md",
     "changelogs/v3.3.4.md",
@@ -167,7 +169,7 @@ var package_default = {
     "test:coverage": "node scripts/run-coverage.cjs",
     "test:audit": "npm audit --omit=dev --registry=https://registry.npmjs.org/",
     test: "npm run build && npm run build:tests && node test/run-tests.cjs",
-    "type-check": "npm run build && tsc -p tsconfig.json --noEmit && tsd --files test/types/root-import.test-d.ts --files test/types/cache-usage.test-d.ts --files test/types/model-usage.test-d.ts --files test/types/pool-usage.test-d.ts --files test/types/sync-usage.test-d.ts --files test/types/slow-query-log-usage.test-d.ts --files test/types/saga-usage.test-d.ts --files test/types/data-tasks-usage.test-d.ts --files test/types/search-index-usage.test-d.ts",
+    "type-check": "npm run build && tsc -p tsconfig.json --noEmit && tsd --files test/types/root-import.test-d.ts --files test/types/cache-usage.test-d.ts --files test/types/model-usage.test-d.ts --files test/types/pool-usage.test-d.ts --files test/types/sync-usage.test-d.ts --files test/types/slow-query-log-usage.test-d.ts --files test/types/saga-usage.test-d.ts --files test/types/data-tasks-usage.test-d.ts --files test/types/search-index-usage.test-d.ts --files test/types/gridfs-usage.test-d.ts",
     "check:test-language": "node scripts/check-test-language.cjs",
     "check:docs-examples": "node scripts/validation/check-doc-example-matrix.cjs",
     "check:release-candidate": "node scripts/check-release-candidate.cjs",