embedoc 0.9.0 → 0.9.1

package/README.md

@@ -872,6 +872,8 @@ npm test
 
 ## API Reference
 
+> 📖 **See [docs/api/README.md](./docs/api/README.md) for detailed Embed API documentation.**
+
 ### Exported Functions
 
 ```typescript

package/dist/embed-api.d.ts

@@ -0,0 +1,49 @@
+/**
+ * embedoc Embed API
+ *
+ * This module exports all types and functions needed for writing custom embeds.
+ *
+ * @example
+ * ```typescript
+ * import { defineEmbed, type EmbedContext, type EmbedResult } from 'embedoc';
+ *
+ * export default defineEmbed({
+ *   dependsOn: ['my_datasource'],
+ *   async render(ctx: EmbedContext): Promise<EmbedResult> {
+ *     const data = await ctx.datasources.my_datasource.query('SELECT * FROM table');
+ *     return { content: ctx.markdown.table(['Column'], data.map(r => [r.name])) };
+ *   }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { 
+/**
+ * Embed definition interface.
+ * Use with {@link defineEmbed} to create custom embeds.
+ */
+EmbedDefinition, 
+/**
+ * Context object passed to the embed's render function.
+ * Provides access to parameters, datasources, and helpers.
+ */
+EmbedContext, 
+/**
+ * Result returned from an embed's render function.
+ */
+EmbedResult, 
+/**
+ * Helper interface for generating Markdown content.
+ */
+MarkdownHelper, 
+/**
+ * Datasource interface for querying data.
+ */
+Datasource, 
+/**
+ * Query result type (array of records).
+ */
+QueryResult, } from './types/index.js';
+export { defineEmbed } from './index.js';
+//# sourceMappingURL=embed-api.d.ts.map

package/dist/embed-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-api.d.ts","sourceRoot":"","sources":["../src/embed-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,YAAY;AACV;;;GAGG;AACH,eAAe;AAEf;;;GAGG;AACH,YAAY;AAEZ;;GAEG;AACH,WAAW;AAEX;;GAEG;AACH,cAAc;AAEd;;GAEG;AACH,UAAU;AAEV;;GAEG;AACH,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/embed-api.js

@@ -0,0 +1,23 @@
+/**
+ * embedoc Embed API
+ *
+ * This module exports all types and functions needed for writing custom embeds.
+ *
+ * @example
+ * ```typescript
+ * import { defineEmbed, type EmbedContext, type EmbedResult } from 'embedoc';
+ *
+ * export default defineEmbed({
+ *   dependsOn: ['my_datasource'],
+ *   async render(ctx: EmbedContext): Promise<EmbedResult> {
+ *     const data = await ctx.datasources.my_datasource.query('SELECT * FROM table');
+ *     return { content: ctx.markdown.table(['Column'], data.map(r => [r.name])) };
+ *   }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Re-export defineEmbed function
+export { defineEmbed } from './index.js';
+//# sourceMappingURL=embed-api.js.map

package/dist/embed-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-api.js","sourceRoot":"","sources":["../src/embed-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqCH,iCAAiC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.d.ts

@@ -26,9 +26,15 @@ export { createDatasource, initializeDatasources, closeDatasources, SqliteDataso
 export { createMarkdownHelper } from './helpers/markdown.js';
 import type { DefineEmbedFn } from './types/index.js';
 /**
- * Helper function to define an embed
+ * Define a custom embed for generating content in documents.
  *
- * @example
+ * Embeds are TypeScript modules that generate content for markers
+ * in your documents. Use this function to create type-safe embed definitions.
+ *
+ * @param definition - The embed definition object
+ * @returns The same definition object (for type inference)
+ *
+ * @example Basic embed
  * ```typescript
  * import { defineEmbed } from 'embedoc';
  *
@@ -36,7 +42,7 @@ import type { DefineEmbedFn } from './types/index.js';
  *   dependsOn: ['metadata_db'],
  *   async render(ctx) {
  *     const { id } = ctx.params;
- *     const data = await ctx.datasources.metadata_db.query(
+ *     const data = await ctx.datasources['metadata_db'].query(
  *       'SELECT * FROM tables WHERE name = ?',
  *       [id]
  *     );
@@ -44,7 +50,54 @@ import type { DefineEmbedFn } from './types/index.js';
  *   }
  * });
  * ```
+ *
+ * @example Embed with multiple datasources
+ * ```typescript
+ * import { defineEmbed } from 'embedoc';
+ *
+ * export default defineEmbed({
+ *   dependsOn: ['users_db', 'config'],
+ *   async render(ctx) {
+ *     const users = await ctx.datasources['users_db'].getAll();
+ *     const config = await ctx.datasources['config'].getAll();
+ *
+ *     return {
+ *       content: ctx.markdown.table(
+ *         ['Name', 'Role'],
+ *         users.map(u => [u.name, u.role])
+ *       )
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @example Embed using frontmatter and parameters
+ * ```typescript
+ * import { defineEmbed } from 'embedoc';
+ *
+ * export default defineEmbed({
+ *   async render(ctx) {
+ *     // Access marker parameters: <!--@embedoc:my_embed title="Hello"-->
+ *     const { title } = ctx.params;
+ *
+ *     // Access document frontmatter
+ *     const author = ctx.frontmatter['author'] as string;
+ *
+ *     return {
+ *       content: ctx.markdown.heading(title, 2) + '\n\nBy ' + author
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link EmbedDefinition} for the definition interface
+ * @see {@link EmbedContext} for the context object passed to render
+ * @see {@link MarkdownHelper} for markdown generation utilities
  */
 export declare const defineEmbed: DefineEmbedFn;
+/**
+ * Alias for {@link defineEmbed}.
+ * @deprecated Use `defineEmbed` instead for consistency.
+ */
 export declare const defineTemplate: DefineEmbedFn;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,YAAY,EAEV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,sBAAsB,EAEtB,YAAY,EACZ,eAAe,EAEf,WAAW,EACX,UAAU,EACV,iBAAiB,EAEjB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EAEb,iBAAiB,EAEjB,aAAa,EACb,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,WAAW,EACX,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3E,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,GACf,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,EAAE,aAA2D,CAAC;AAGtF,eAAO,MAAM,cAAc,eAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,YAAY,EAEV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,sBAAsB,EAEtB,YAAY,EACZ,eAAe,EAEf,WAAW,EACX,UAAU,EACV,iBAAiB,EAEjB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EAEb,iBAAiB,EAEjB,aAAa,EACb,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,WAAW,EACX,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3E,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,GACf,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,eAAO,MAAM,WAAW,EAAE,aAA2D,CAAC;AAEtF;;;GAGG;AACH,eAAO,MAAM,cAAc,eAAc,CAAC"}

package/dist/index.js

@@ -26,9 +26,15 @@ export { createDatasource, initializeDatasources, closeDatasources, SqliteDataso
 // Helpers
 export { createMarkdownHelper } from './helpers/markdown.js';
 /**
- * Helper function to define an embed
+ * Define a custom embed for generating content in documents.
  *
- * @example
+ * Embeds are TypeScript modules that generate content for markers
+ * in your documents. Use this function to create type-safe embed definitions.
+ *
+ * @param definition - The embed definition object
+ * @returns The same definition object (for type inference)
+ *
+ * @example Basic embed
  * ```typescript
  * import { defineEmbed } from 'embedoc';
  *
@@ -36,7 +42,7 @@ export { createMarkdownHelper } from './helpers/markdown.js';
  *   dependsOn: ['metadata_db'],
  *   async render(ctx) {
  *     const { id } = ctx.params;
- *     const data = await ctx.datasources.metadata_db.query(
+ *     const data = await ctx.datasources['metadata_db'].query(
  *       'SELECT * FROM tables WHERE name = ?',
  *       [id]
  *     );
@@ -44,8 +50,54 @@ export { createMarkdownHelper } from './helpers/markdown.js';
  *   }
  * });
  * ```
+ *
+ * @example Embed with multiple datasources
+ * ```typescript
+ * import { defineEmbed } from 'embedoc';
+ *
+ * export default defineEmbed({
+ *   dependsOn: ['users_db', 'config'],
+ *   async render(ctx) {
+ *     const users = await ctx.datasources['users_db'].getAll();
+ *     const config = await ctx.datasources['config'].getAll();
+ *
+ *     return {
+ *       content: ctx.markdown.table(
+ *         ['Name', 'Role'],
+ *         users.map(u => [u.name, u.role])
+ *       )
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @example Embed using frontmatter and parameters
+ * ```typescript
+ * import { defineEmbed } from 'embedoc';
+ *
+ * export default defineEmbed({
+ *   async render(ctx) {
+ *     // Access marker parameters: <!--@embedoc:my_embed title="Hello"-->
+ *     const { title } = ctx.params;
+ *
+ *     // Access document frontmatter
+ *     const author = ctx.frontmatter['author'] as string;
+ *
+ *     return {
+ *       content: ctx.markdown.heading(title, 2) + '\n\nBy ' + author
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link EmbedDefinition} for the definition interface
+ * @see {@link EmbedContext} for the context object passed to render
+ * @see {@link MarkdownHelper} for markdown generation utilities
  */
 export const defineEmbed = (definition) => definition;
-// Export alias for documentation consistency
+/**
+ * Alias for {@link defineEmbed}.
+ * @deprecated Use `defineEmbed` instead for consistency.
+ */
 export const defineTemplate = defineEmbed;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmCH,iBAAiB;AACjB,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,oBAAoB;AACpB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,WAAW,EACX,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,cAAc;AACd,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,GACf,MAAM,wBAAwB,CAAC;AAEhC,UAAU;AACV,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAK7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAkB,CAAC,UAA2B,EAAE,EAAE,CAAC,UAAU,CAAC;AAEtF,6CAA6C;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmCH,iBAAiB;AACjB,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,oBAAoB;AACpB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,WAAW,EACX,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,cAAc;AACd,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,GACf,MAAM,wBAAwB,CAAC;AAEhC,UAAU;AACV,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAK7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAkB,CAAC,UAA2B,EAAE,EAAE,CAAC,UAAU,CAAC;AAEtF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC"}