Skip to content

Commit 4e93bf0

Browse files
addaleaxaddaleax
committed
Add README, move packages to @mongosh/snippet-...
1 parent 4353faf commit 4e93bf0

File tree

6 files changed

+156
-7
lines changed

6 files changed

+156
-7
lines changed

‎README.md

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# mongosh-snippets
2+
3+
An experimental plugin feature for [mongosh][].
4+
5+
## What is a snippet?
6+
7+
A snippet is a script that you can install using the `snippet` command in [mongosh][],
8+
to provide additional functionality that mongosh does otherwise not provide.
9+
10+
## What does it mean that snippets are experimental?
11+
12+
It means that, for the time being, MongoDB does not offer any commercial
13+
support for it, and that it may be changed or removed as we see fit.
14+
15+
It does not mean that bugs in this feature are an expected occurrence, and you
16+
can and should file bugs in the mongosh [JIRA][] project if you experience any.
17+
18+
## How do I install a snippet?
19+
20+
You can manage snippets through the `snippet` command in mongosh. Running
21+
`snippet help` gives an overview over all commands that are available.
22+
23+
For installing a snippet, you can use `snippet install <name>`:
24+
25+
```
26+
> snippet uninstall analyze-schema
27+
Running uninstall...
28+
Done!
29+
> snippet install analyze-schema
30+
Running install...
31+
Installed new snippets analyze-schema. Do you want to load them now? [Y/n]: y
32+
Finished installing snippets: analyze-schema
33+
> db.test.insertOne({ field: 'value' })
34+
{
35+
acknowledged: true,
36+
insertedId: ObjectId("60b60758d381fd904f5dc517")
37+
}
38+
> schema(db.test)
39+
┌─────────┬─────────┬───────────┬────────────┐
40+
│ (index) │ 0 │ 1 │ 2 │
41+
├─────────┼─────────┼───────────┼────────────┤
42+
│ 0 │ '_id ' │ '100.0 %' │ 'ObjectID' │
43+
│ 1 │ 'field' │ '100.0 %' │ 'String' │
44+
└─────────┴─────────┴───────────┴────────────┘
45+
```
46+
47+
You can list all installed snippets with `snippet ls`, and you can list all
48+
available snippets with `snippet search`.
49+
50+
## Can I disable this feature?
51+
52+
Yes.
53+
54+
```
55+
> config.set('snippetIndexSourceURLs', '')
56+
```
57+
58+
## How do snippets work?
59+
60+
The snippets feature uses the [npm][] package manager under the hood to install
61+
snippets from a pre-specified registry. The default registry currently points to
62+
this Github repository here. When you install a snippet, mongosh will look up
63+
its npm package name based on the information in the registry and install it,
64+
and load it using `load()` by default on each mongosh startup.
65+
66+
This also means that snippets can depend on npm packages, and use them in their
67+
functionality. For example, the `analyze-schema` example above uses the
68+
[`mongodb-schema`][] package from npm to perform the analysis itself.
69+
70+
## Can I add my own snippets?
71+
72+
Absolutely! You should feel encouraged to do so, if you believe that you have
73+
a script for the shell that you think others might find useful as well.
74+
75+
In order to add a new snippet:
76+
- Fork and clone this repository
77+
- Add a new directory under `snippets/`, using the name you wish to use
78+
- Add at least the `package.json`, `index.js` and `LICENSE` files, and ideally
79+
also a short `README.md`.
80+
81+
A minimal package.json could contain:
82+
83+
```js
84+
{
85+
"name": "@mongosh/snippet-<name>",
86+
"snippetName": "<name>",
87+
"version": "0.0.1",
88+
"description": "...",
89+
"main": "index.js",
90+
"license": "Apache-2.0",
91+
"publishConfig": {
92+
"access": "public"
93+
}
94+
}
95+
```
96+
97+
Once you have completed that, you can commit your changes and open a pull
98+
request against this repository.
99+
100+
If it is merged, we will take care of publishing and adding it to the index.
101+
102+
## Can I run my own registry?
103+
104+
Yes. From the mongosh CLI perspective, a snippet registry is just a https URL
105+
pointing to a [brotli][]-compressed [BSON][] file; no package contents are
106+
actually provided in that file. This file has the following format (
107+
in TypeScript syntax):
108+
109+
```typescript
110+
interface ErrorMatcher {
111+
// Add additional information to shell errors matching one of the regular.
112+
// expressions. The message can point to a snippet helping solve that error.
113+
matches: RegExp[];
114+
message: string;
115+
}
116+
117+
interface SnippetDescription {
118+
// The *npm* package name. Users do not interact with this.
119+
name: string;
120+
// The snippet name. This is what users interact with.
121+
snippetName: string;
122+
// An optional install specifier that can be used to point npm towards
123+
// packages that are not uploaded to the registry. For example,
124+
// this could be an URL to a git repository or a tarball.
125+
installSpec?: string;
126+
// A version field. Users do not interact with this, as currently, `snippet`
127+
// always installs the latest versions of snippets.
128+
version: string;
129+
description: string;
130+
readme: string;
131+
// License should be a SPDX license identifier.
132+
license: string;
133+
errorMatchers?: ErrorMatcher[];
134+
}
135+
136+
interface SnippetIndexFile {
137+
// This must be 1 currently.
138+
indexFileVersion: 1;
139+
index: SnippetDescription[];
140+
metadata: { homepage: string };
141+
}
142+
```
143+
144+
[mongosh]: https://github.com/mongodb-js/mongosh
145+
[JIRA]: https://jira.mongodb.org/projects/MONGOSH/issues
146+
[npm]: https://www.npmjs.com/
147+
[`mongodb-schema`]: https://www.npmjs.com/package/mongodb-schema
148+
[brotli]: https://github.com/google/brotli/
149+
[BSON]: https://bsonspec.org/

‎package.json

+3-3
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,12 @@
99
"make-index": "node scripts/make-index",
1010
"show-index": "node scripts/show-index"
1111
},
12-
"homepage": "https://github.com/addaleax/mongosh-snippets",
12+
"homepage": "https://github.com/mongodb-js/mongosh-snippets",
1313
"repository": {
1414
"type": "git",
15-
"url": "https://github.com/addaleax/mongosh-snippets.git"
15+
"url": "https://github.com/mongodb-js/mongosh-snippets.git"
1616
},
1717
"bugs": {
18-
"url": "https://github.com/addaleax/mongosh-snippets/issues"
18+
"url": "https://github.com/mongodb-js/mongosh-snippets/issues"
1919
}
2020
}

‎snippets/analyze-schema/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@addaleax/test-mongosh-snippet-analyze-schema",
2+
"name": "@mongosh/snippet-analyze-schema",
33
"snippetName": "analyze-schema",
44
"version": "1.0.4",
55
"description": "schema(db.coll)",

‎snippets/mock-collection/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@addaleax/test-mongosh-snippet-mock-collection",
2+
"name": "@mongosh/snippet-mock-collection",
33
"snippetName": "mock-collection",
44
"version": "1.0.1",
55
"description": "mockCollection([{ a: 1 }, { a: 2 }]).find({ a: { $gt: 2 } })",

‎snippets/mongocompat/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@addaleax/test-mongosh-snippet-mongocompat",
2+
"name": "@mongosh/snippet-mongocompat",
33
"snippetName": "mongocompat",
44
"version": "1.0.5",
55
"description": "mongo compatibility script for mongosh",

‎snippets/spawn-mongod/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@addaleax/test-mongosh-snippet-spawn-mongod",
2+
"name": "@mongosh/snippet-spawn-mongod",
33
"snippetName": "spawn-mongod",
44
"version": "1.0.0",
55
"description": "Spin up a local mongod process",

0 commit comments

Comments
 (0)