@documentdb-js/shell-api-types 0.8.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -0,0 +1,105 @@
+# @documentdb-js/shell-api-types
+
+[DocumentDB](https://documentdb.io/) is an open-source document database built on PostgreSQL, with native BSON support, rich indexing, and vector search. It uses the MongoDB-compatible wire protocol, runs locally with Docker, and is MIT licensed.
+
+This package provides TypeScript type definitions and a structured method-to-command registry for the DocumentDB shell API — everything needed to build IntelliSense, documentation tooling, or compatibility checks for the DocumentDB shell surface.
+
+> **Pre-1.0 notice** — The API may change between minor versions until `1.0.0` is released.
+> If you depend on this package and need stability guarantees sooner, please
+> [open an issue](https://github.com/microsoft/vscode-documentdb/issues) and let us know.
+
+## What This Package Provides
+
+1. **`documentdb-shell-api.d.ts`** — TypeScript declarations for the DocumentDB
+   shell API surface (database methods, collection methods, cursor methods, BSON
+   constructors, and shell globals). Can be injected into a TS Server Plugin
+   for autocompletion, hover documentation, and signature help.
+
+2. **Method registry** — A structured mapping of every shell method to its
+   underlying DocumentDB server command(s). Methods that are client-side only
+   (e.g., `use()`, `help()`, `getSiblingDB()`) are flagged as `shellOnly`.
+
+3. **Compatibility verification** — A script that checks the method registry
+   against the official
+   [DocumentDB compatibility documentation](https://learn.microsoft.com/en-us/azure/documentdb/compatibility-query-language)
+   to detect when the upstream support matrix changes.
+
+## How the API Surface Was Determined
+
+DocumentDB uses the MongoDB wire protocol. As stated in the
+[official compatibility documentation](https://learn.microsoft.com/en-us/azure/documentdb/compatibility-query-language):
+
+> "Client-side wrapper functions, such as `deleteMany()` and `updateMany()`,
+> internally invoke the corresponding server commands (`delete()` and
+> `update()`). Any function that relies on supported server commands is
+> compatible with Azure DocumentDB."
+
+The methods in this package were **manually selected** to provide a productive
+shell editing experience. Each method maps to a server-side command listed
+as supported in the DocumentDB compatibility matrix. All JSDoc
+descriptions are original writing.
+
+See [`typeDefs/README.md`](typeDefs/README.md) for the full list of reference
+documentation pages.
+
+## Installation
+
+```bash
+npm install @documentdb-js/shell-api-types
+```
+
+## Usage
+
+```typescript
+import {
+  getShellApiDtsContent,
+  SHELL_API_METHODS,
+  getRequiredServerCommands,
+  getMethodsByTarget,
+} from '@documentdb-js/shell-api-types';
+
+// Get the .d.ts content as a string (for TS server plugin injection)
+const dtsContent = getShellApiDtsContent();
+
+// Get all methods for a specific target
+const collectionMethods = getMethodsByTarget('collection');
+
+// Get the list of server commands the shell API depends on
+const serverCommands = getRequiredServerCommands();
+```
+
+## Scripts
+
+| Script           | Description                                                          |
+| ---------------- | -------------------------------------------------------------------- |
+| `npm run build`  | Compile TypeScript sources                                           |
+| `npm run test`   | Run unit tests (method registry)                                     |
+| `npm run verify` | Check method registry against official DocumentDB compatibility docs |
+
+### Verification (`npm run verify`)
+
+The `verify` script fetches the official DocumentDB compatibility page,
+extracts the Database Commands table, and checks that every server command
+referenced by the shell API is still marked as supported.
+
+**Output keys** (for CI `grep`/`contains` checks):
+
+| Key                               | Meaning                                                          |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `[SHELL-API-COMPATIBLE]`          | All server commands verified as supported — no action needed     |
+| `[SHELL-API-INCOMPATIBLE]`        | A referenced command is no longer supported — update the `.d.ts` |
+| `[SHELL-API-UNSUPPORTED-COMMAND]` | Per-command detail for each incompatible command                 |
+| `[SHELL-API-MISSING-COMMAND]`     | A referenced command was not found in the docs table             |
+| `[SHELL-API-NEW-COMMANDS]`        | New supported commands found that could be added to the API      |
+
+The script also generates a full report at
+`resources/scraped/compatibility-commands.md` with supported/unsupported command
+tables and the complete method-to-command mapping.
+
+## Origin
+
+This package was developed while building features for the [DocumentDB VS Code extension](https://github.com/microsoft/vscode-documentdb), which remains the primary consumer. The package is designed to be useful in any tooling that needs DocumentDB shell API type information or method metadata.
+
+## License
+
+[MIT](LICENSE.md)

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @documentdb-js/shell-api-types
+ *
+ * Shell API type definitions and method-to-command mapping for DocumentDB
+ * query playground IntelliSense. This package provides:
+ *
+ *   1. The `.d.ts` content as a string — used by the TS Server Plugin to
+ *      inject type declarations into query playground files.
+ *   2. A method registry mapping each shell method to its underlying server
+ *      command(s) — used for compatibility verification.
+ *   3. A verification script (`npm run verify`) that checks the method
+ *      registry against the official DocumentDB compatibility documentation.
+ */
+export type { ShellMethodEntry } from './types';
+export { SHELL_API_METHODS, getMethodsByTarget, getRequiredServerCommands } from './methodRegistry';
+/**
+ * Returns the full content of the DocumentDB shell API `.d.ts` file.
+ * The content is read from disk once and cached in memory.
+ */
+export declare function getShellApiDtsContent(): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AAGH,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAQpG;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C"}

package/dist/index.js

@@ -0,0 +1,62 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRequiredServerCommands = exports.getMethodsByTarget = exports.SHELL_API_METHODS = void 0;
+exports.getShellApiDtsContent = getShellApiDtsContent;
+// Method registry
+var methodRegistry_1 = require("./methodRegistry");
+Object.defineProperty(exports, "SHELL_API_METHODS", { enumerable: true, get: function () { return methodRegistry_1.SHELL_API_METHODS; } });
+Object.defineProperty(exports, "getMethodsByTarget", { enumerable: true, get: function () { return methodRegistry_1.getMethodsByTarget; } });
+Object.defineProperty(exports, "getRequiredServerCommands", { enumerable: true, get: function () { return methodRegistry_1.getRequiredServerCommands; } });
+// .d.ts content — loaded lazily on first access
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let _dtsContent;
+/**
+ * Returns the full content of the DocumentDB shell API `.d.ts` file.
+ * The content is read from disk once and cached in memory.
+ */
+function getShellApiDtsContent() {
+    if (_dtsContent === undefined) {
+        const dtsPath = path.join(__dirname, '..', 'typeDefs', 'documentdb-shell-api.d.ts');
+        _dtsContent = fs.readFileSync(dtsPath, 'utf8');
+    }
+    return _dtsContent;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgChG,sDAMC;AAnBD,kBAAkB;AAClB,mDAAoG;AAA3F,mHAAA,iBAAiB,OAAA;AAAE,oHAAA,kBAAkB,OAAA;AAAE,2HAAA,yBAAyB,OAAA;AAEzE,gDAAgD;AAChD,uCAAyB;AACzB,2CAA6B;AAE7B,IAAI,WAA+B,CAAC;AAEpC;;;GAGG;AACH,SAAgB,qBAAqB;IACjC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,2BAA2B,CAAC,CAAC;QACpF,WAAW,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,WAAW,CAAC;AACvB,CAAC"}

package/dist/methodRegistry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shell API method registry — maps every method in the DocumentDB shell API
+ * `.d.ts` to its underlying server command(s).
+ *
+ * This registry serves two purposes:
+ *   1. Verification: the `verify` script checks that every server command
+ *      listed here is still marked as supported in the official Azure
+ *      DocumentDB compatibility documentation.
+ *   2. Reference: documents the relationship between client-side shell
+ *      methods and the server commands they invoke.
+ *
+ * Methods are organized by target object (database, collection, cursor, global).
+ * Shell-only methods (no server command) are flagged with `shellOnly: true`.
+ */
+import { type ShellMethodEntry } from './types';
+/** All shell API methods across all target objects. */
+export declare const SHELL_API_METHODS: readonly ShellMethodEntry[];
+/**
+ * Returns all unique server commands referenced by the shell API methods.
+ * These are the commands that must be supported by the DocumentDB server
+ * for the shell API to function correctly.
+ */
+export declare function getRequiredServerCommands(): readonly string[];
+/**
+ * Returns methods filtered by target object.
+ */
+export declare function getMethodsByTarget(target: ShellMethodEntry['target']): readonly ShellMethodEntry[];
+//# sourceMappingURL=methodRegistry.d.ts.map

package/dist/methodRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"methodRegistry.d.ts","sourceRoot":"","sources":["../src/methodRegistry.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAwjBhD,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,EAAE,SAAS,gBAAgB,EAMxD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,SAAS,MAAM,EAAE,CAQ7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAAG,SAAS,gBAAgB,EAAE,CAElG"}