deno.land / x / mongoose@6.7.5 / docs / source / api.js
نووسراو ببینە
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360'use strict';
/*! * Module dependencies */
const dox = require('dox');const fs = require('fs');const md = require('marked');
const files = [ 'lib/index.js', 'lib/schema.js', 'lib/connection.js', 'lib/document.js', 'lib/model.js', 'lib/query.js', 'lib/cursor/QueryCursor.js', 'lib/aggregate.js', 'lib/cursor/AggregationCursor.js', 'lib/schematype.js', 'lib/virtualtype.js', 'lib/error/index.js', 'lib/schema/array.js', 'lib/schema/documentarray.js', 'lib/schema/SubdocumentPath.js', 'lib/options/SchemaTypeOptions.js', 'lib/options/SchemaArrayOptions.js', 'lib/options/SchemaBufferOptions.js', 'lib/options/SchemaDateOptions.js', 'lib/options/SchemaNumberOptions.js', 'lib/options/SchemaObjectIdOptions.js', 'lib/options/SchemaStringOptions.js', 'lib/types/DocumentArray/methods/index.js', 'lib/types/subdocument.js', 'lib/types/ArraySubdocument.js', 'lib/types/buffer.js', 'lib/types/decimal128.js', 'lib/types/map.js'];
module.exports = { docs: [], github: 'https://github.com/Automattic/mongoose/blob/', title: 'API docs', api: true};
const out = module.exports.docs;
const combinedFiles = [];for (const file of files) { try { const comments = dox.parseComments(fs.readFileSync(`./${file}`, 'utf8'), { raw: true }); comments.file = file; combinedFiles.push(comments); } catch (err) { // show log of which file has thrown a error for easier debugging console.error("Error while trying to parseComments for ", file); throw err; }}
parse();
/** * @typedef {Object} TagObject * @property {String} name The Processed name of the Tag (already includes all processing) * @property {String} description The Description of this Tag * @property {Boolean} optional Defines wheter the Tag is optional or not (already included in `name`) * @property {Boolean} nullable Defines wheter the Tag is nullable (dox does not add "null" by default) * @property {Boolean} nonNullable Unknown (invert of `nullable`?) * @property {Boolean} variable Defines wheter the type is spreadable ("...Type") * @property {String[]} types Collection of all types this Tag has * @property {String} type The Type of the Tag * @property {String} string The full string of types plus name plus description (unused in mongoose) * @property {String} typesDescription Processed `types` into markdown code (unused in mongoose) */
/** * @typedef {Object} SeeObject * @property {String} text The text to display the link as * @property {String} [url] The link the text should have as href */
/** * @typedef {Object} PropContext * @property {boolean} [isStatic] Defines wheter the current property is a static property (not mutually exlusive with "isInstance") * @property {boolean} [isInstance] Defines wheter the current property is a instance property (not mutually exlusive with "isStatic") * @property {boolean} [isFunction] Defines wheter the current property is meant to be a function * @property {string} [constructor] Defines the Constructor (or rather path) the current property is on * @property {boolean} [constructorWasUndefined] Defined wheter the "constructor" property was defined by "dox", but was set to "undefined" * @property {string} [type] Defines the type the property is meant to be * @property {string} [name] Defines the current Properties name * @property {TagObject} [return] The full object for a "@return" jsdoc tag * @property {string} [string] Defines the full string the property will be listed as * @property {string} [anchorId] Defines the Anchor ID to be used for linking * @property {string} [description] Defines the Description the property will be listed with * @property {string} [deprecated] Defines wheter the current Property is signaled as deprecated * @property {SeeObject[]} [see] Defines all "@see" references * @property {TagObject[]} [param] Defines all "@param" references * @property {SeeObject} [inherits] Defines the string for "@inherits" */
function parse() { for (const props of combinedFiles) { let name = props.file. replace('lib/', ''). replace('.js', ''). replace('/index', ''). replace('/methods', ''); const lastSlash = name.lastIndexOf('/'); const fullName = name; name = name.substr(lastSlash === -1 ? 0 : lastSlash + 1); if (name === 'core_array') { name = 'array'; } if (fullName === 'schema/array') { name = 'SchemaArray'; } if (name === 'documentarray') { name = 'DocumentArrayPath'; } if (name === 'DocumentArray') { name = 'MongooseDocumentArray'; } const data = { name: name.charAt(0).toUpperCase() === name.charAt(0) ? name : name.charAt(0).toUpperCase() + name.substr(1), props: [] };
for (const prop of props) { if (prop.ignore || prop.isPrivate) { continue; } /** @type {PropContext} */ const ctx = prop.ctx || {};
// somehow in "dox", it is named "receiver" sometimes, not "constructor" // this is used as a fall-back if the handling below does not overwrite it if ("receiver" in ctx) { ctx.constructor = ctx.receiver; delete ctx.receiver; }
// in some cases "dox" has "ctx.constructor" defined but set to "undefined", which will later be used for setting "ctx.string" if ("constructor" in ctx && ctx.constructor === undefined) { ctx.constructorWasUndefined = true; }
// helper function to keep translating array types to string consistent function convertTypesToString(types) { return Array.isArray(types) ? types.join('|') : types }
for (const __tag of prop.tags) { // the following has been done, because otherwise no type could be applied for intellisense /** @type {TagObject} */ const tag = __tag; switch (tag.type) { case 'see': if (!Array.isArray(ctx.see)) { ctx.see = []; }
// for this type, it needs to be parsed from the string itself to support more than 1 word // this is required because "@see" is kinda badly defined and mongoose uses a slightly customized way (longer text and different kinds of links)
ctx.see.push(extractTextUrlFromTag(tag, ctx, true)); break; case 'receiver': console.warn(`Found "@receiver" tag in ${ctx.constructor} ${ctx.name}`); break; case 'property': ctx.type = 'property';
// using "name" over "string" because "string" also contains the type and maybe other stuff ctx.name = tag.name; // only assign "type" if there are types if (tag.types.length > 0) { ctx.type = convertTypesToString(tag.types); }
break; case 'type': ctx.type = convertTypesToString(tag.types); break; case 'static': ctx.type = 'property'; ctx.isStatic = true; // dont take "string" as "name" from here, because jsdoc definitions of "static" do not have parameters, also its defined elsewhere anyway // ctx.name = tag.string; break; case 'function': ctx.type = 'function'; ctx.isStatic = true; ctx.name = tag.string; // extra parameter to make function definitions independant of where "@function" is defined // like "@static" could have overwritten "ctx.string" again if defined after "@function" ctx.isFunction = true; break; case 'return': tag.description = tag.description ? md.parse(tag.description).replace(/^<p>/, '').replace(/<\/p>\n?$/, '') : '';
// dox does not add "void" / "undefined" to types, so in the documentation it would result in a empty "«»" if (tag.string.includes('void') || tag.string.includes('undefined')) { tag.types.push("void"); }
ctx.return = tag; break; case 'inherits': ctx.inherits = extractTextUrlFromTag(tag, ctx); break; case 'event': case 'param': ctx[tag.type] = (ctx[tag.type] || []); // the following is required, because in newer "dox" version "null" is not included in "types" anymore, but a seperate property if (tag.nullable) { tag.types.push('null'); } if (tag.types) { tag.types = convertTypesToString(tag.types); } ctx[tag.type].push(tag); if (tag.name != null && tag.name.startsWith('[') && tag.name.endsWith(']') && tag.name.includes('.')) { tag.nested = true; } if (tag.variable) { if (tag.name.startsWith('[')) { tag.name = '[...' + tag.name.slice(1); } else { tag.name = '...' + tag.name; } } tag.description = tag.description ? md.parse(tag.description).replace(/^<p>/, '').replace(/<\/p>$/, '') : ''; break; case 'method': ctx.type = 'method'; ctx.name = tag.string; ctx.isFunction = true; break; case 'memberOf': ctx.constructor = tag.parent; break; case 'constructor': ctx.string = tag.string; ctx.name = tag.string; ctx.isFunction = true; break; case 'instance': ctx.isInstance = true; break; case 'deprecated': ctx.deprecated = true; break; } }
if (ctx.isInstance && ctx.isStatic) { console.warn(`Property "${ctx.name}" in "${ctx.constructor}" has both instance and static JSDOC markings (most likely both @instance and @static)! (File: "${props.file}")`); }
// the following if-else-if statement is in this order, because there are more "instance" methods thans static // the following condition will be true if "isInstance = true" or if "isInstance = false && isStatic = false" AND "ctx.string" are empty or not defined // if "isStatic" and "isInstance" are falsy and "ctx.string" is not falsy, then rely on the "ctx.string" set by "dox" if (ctx.isInstance || (!ctx.isStatic && !ctx.isInstance && (!ctx.string || ctx.constructorWasUndefined))) { ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; } else if (ctx.isStatic) { ctx.string = `${ctx.constructor}.${ctx.name}`; }
// add "()" to the end of the string if function if ((ctx.isFunction || ctx.type === "method") && !ctx.string.endsWith("()")) { ctx.string = ctx.string + "()"; }
// Backwards compat anchors if (typeof ctx.constructor === 'string') { ctx.anchorId = `${ctx.constructor.toLowerCase()}_${ctx.constructor}-${ctx.name}`; } else if (typeof ctx.receiver === 'string') { ctx.anchorId = `${ctx.receiver.toLowerCase()}_${ctx.receiver}.${ctx.name}`; } else { ctx.anchorId = `${ctx.name.toLowerCase()}_${ctx.name}`; }
ctx.description = prop.description.full. replace(/<br \/>/ig, ' '). replace(/>/ig, '>'); ctx.description = md.parse(ctx.description);
data.props.push(ctx); }
data.props.sort(function(a, b) { if (a.string < b.string) { return -1; } else { return 1; } });
if (props.file.startsWith('lib/options')) { data.hideFromNav = true; }
data.file = props.file; data.editLink = 'https://github.com/Automattic/mongoose/blob/master/' + props.file;
out.push(data); }}
/** * Extract the Text and Url from a description if any * @param {Tag} tag The tag to process the resulting object from * @param {PropContext} ctx The current ctx for warnings * @param {Boolean} warnOnMissingUrl Warn if the url is missing, false by default * @returns {{ text: string, url: string }} */function extractTextUrlFromTag(tag, ctx, warnOnMissingUrl = false) { // the following regex matches cases of: // "External Links http://someurl.com/" -> "External Links" // "External https://someurl.com/" -> "External" // "Id href #some_Some-method" -> "Id href" // "Local Absolute /docs/somewhere" -> "Local Absolute" // "No Href" -> "No Href" // "https://someurl.com" -> "" (fallback added) // "Some#Method #something" -> "Some#Method" // The remainder is simply taken by a call to "slice" (also the text is trimmed later) const textMatches = /^(.*? (?=#|\/|(?:https?:)|$))/i.exec(tag.string);
let text = undefined; let url = undefined; if (textMatches === null || textMatches === undefined) { if (warnOnMissingUrl) { // warn for the cases where URL should be defined (like in "@see") console.warn(`No Text Matches found in tag for "${ctx.constructor}.${ctx.name}"`) }
// if no text is found, add text as url and use the url itself as the text url = tag.string; text = tag.string; } else { text = textMatches[1].trim(); url = tag.string.slice(text.length).trim(); }
return { text: text || 'No Description', // fallback text, so that the final text does not end up as a empty element that cannot be seen url: url || undefined, // change to be "undefined" if text is empty or non-valid };}
mongoose
Version Info
a year ago
