part1

src/store/company/create.js

@@ -11,29 +11,34 @@ import langEnsure from '../lang/ensure.js';
 import taxEnsure from '../tax/ensure.js';
 import request from '../request.js';
 
-/**
- * Creates a new company together with its root category, POS customer group,
- * default language and tax rates, and links it to the given Google auth user.
- *
- * @param {object} pool - The mssql connection pool.
- * @returns {Function} An async function that creates a company.
- *
- * @example
- * const fn = create(pool);
- * const company = await fn({
- *   iso639: 'de',
- *   name: 'Acme',
- *   taxrate: 19,
- *   reducedtaxrate: 7,
- *   googleAuthId: 42,
- * });
- * // => { id, rootCategoryId, languageId, taxrateId, reducedtaxrateId, taxfreerateId, posCustomerGroupId }
- */
 export default function create(pool) {
   const nameTaken = getByName(pool);
   const ensureLang = langEnsure(pool);
   const ensureTax = taxEnsure(pool);
 
+  /**
+   * Creates a new company together with its root category, POS customer group,
+   * default language and tax rates, and links it to the given Google auth user.
+   *
+   * @param {object} input - The company creation input.
+   * @param {string} input.iso639 - The ISO 639 language code for the company.
+   * @param {string} input.name - The company name (must be unique).
+   * @param {number} input.taxrate - The standard tax rate in percent.
+   * @param {number} input.reducedtaxrate - The reduced tax rate in percent.
+   * @param {number} input.googleAuthId - The id of the Google auth user to link.
+   * @returns {Promise<{id: number, rootCategoryId: number, languageId: number, taxrateId: number, reducedtaxrateId: number, taxfreerateId: number, posCustomerGroupId: number}>} The created company ids.
+   * @throws {Error} If the company name is already taken.
+   *
+   * @example
+   * const company = await store.company.create({
+   *   iso639: 'de',
+   *   name: 'Acme',
+   *   taxrate: 19,
+   *   reducedtaxrate: 7,
+   *   googleAuthId: 42,
+   * });
+   * // => { id, rootCategoryId, languageId, taxrateId, reducedtaxrateId, taxfreerateId, posCustomerGroupId }
+   */
   return async ({ iso639, name, taxrate, reducedtaxrate, googleAuthId }) => {
     const tx = pool.transaction();
     await tx.begin();

src/store/company/delete.js

@@ -1,16 +1,15 @@
 import { DELETE } from '../../sql/company.js';
 
-/**
- * Deletes a company by its id.
- *
- * @param {object} pool - The mssql connection pool.
- * @returns {Function} An async function that deletes a company.
- *
- * @example
- * const fn = del(pool);
- * await fn(1);
- */
 export default function del(pool) {
+  /**
+   * Deletes a company by its id.
+   *
+   * @param {number} companyId - The id of the company to delete.
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await store.company.delete(1);
+   */
   return async (companyId) => {
     await pool
       .request()

src/store/company/getById.js

@@ -1,18 +1,18 @@
 import { GET_BY_ID } from '../../sql/company.js';
 import request from '../request.js';
 
-/**
- * Returns a single company by its id.
- *
- * @param {object} pool - The mssql connection pool.
- * @returns {Function} An async function that fetches a company by id.
- *
- * @example
- * const fn = getById(pool);
- * const company = await fn(1);
- * // => { id, name, ... }
- */
 export default function getById(pool) {
+  /**
+   * Returns a single company by its id.
+   *
+   * @param {number} id - The id of the company.
+   * @param {object} [tx] - Optional transaction to run within.
+   * @returns {Promise<object|undefined>} The company row, or `undefined` if not found.
+   *
+   * @example
+   * const company = await store.company.getById(1);
+   * // => { id, name, ... }
+   */
   return async (id, tx) => {
     const result = await request(pool, tx)
       .input('id', id)

src/store/company/getByName.js

@@ -1,18 +1,18 @@
 import { GET_BY_NAME } from '../../sql/company.js';
 import request from '../request.js';
 
-/**
- * Returns a single company by its name.
- *
- * @param {object} pool - The mssql connection pool.
- * @returns {Function} An async function that fetches a company by name.
- *
- * @example
- * const fn = getByName(pool);
- * const company = await fn('Acme');
- * // => { id, name, ... }
- */
 export default function getByName(pool) {
+  /**
+   * Returns a single company by its name.
+   *
+   * @param {string} name - The company name.
+   * @param {object} [tx] - Optional transaction to run within.
+   * @returns {Promise<object|undefined>} The company row, or `undefined` if not found.
+   *
+   * @example
+   * const company = await store.company.getByName('Acme');
+   * // => { id, name, ... }
+   */
   return async (name, tx) => {
     const result = await request(pool, tx)
       .input('name', name)

src/store/company/list.js

@@ -1,17 +1,16 @@
 import { LIST } from '../../sql/company.js';
 
-/**
- * Lists the companies accessible to the given Google auth user.
- *
- * @param {object} pool - The mssql connection pool.
- * @returns {Function} An async function that lists companies.
- *
- * @example
- * const fn = list(pool);
- * const companies = await fn(42);
- * // => [{ id, name, ... }]
- */
 export default function list(pool) {
+  /**
+   * Lists the companies accessible to the given Google auth user.
+   *
+   * @param {number} googleAuthId - The id of the Google auth user.
+   * @returns {Promise<Array<object>>} The accessible company rows.
+   *
+   * @example
+   * const companies = await store.company.list(42);
+   * // => [{ id, name, ... }]
+   */
   return async (googleAuthId) => {
     const result = await pool
       .request()

src/store/company/update.js

@@ -5,23 +5,28 @@ import langEnsure from '../lang/ensure.js';
 import taxEnsure from '../tax/ensure.js';
 import request from '../request.js';
 
-/**
- * Updates an existing company's name, language and tax rates.
- *
- * @param {object} pool - The mssql connection pool.
- * @returns {Function} An async function that updates a company.
- *
- * @example
- * const fn = update(pool);
- * const result = await fn(1, { iso639: 'de', name: 'Acme', taxrate: 19, reducedtaxrate: 7 });
- * // => { id, rootCategoryId, languageId, taxrateId, reducedtaxrateId, taxfreerateId }
- */
 export default function update(pool) {
   const byId = getById(pool);
   const byName = getByName(pool);
   const ensureLang = langEnsure(pool);
   const ensureTax = taxEnsure(pool);
 
+  /**
+   * Updates an existing company's name, language and tax rates.
+   *
+   * @param {number} id - The id of the company to update.
+   * @param {object} input - The update input.
+   * @param {string} input.iso639 - The ISO 639 language code.
+   * @param {string} input.name - The new company name (must be unique).
+   * @param {number} input.taxrate - The standard tax rate in percent.
+   * @param {number} input.reducedtaxrate - The reduced tax rate in percent.
+   * @returns {Promise<{id: number, rootCategoryId: number, languageId: number, taxrateId: number, reducedtaxrateId: number, taxfreerateId: number}>} The updated company ids.
+   * @throws {Error} If the company is not found or the name is taken.
+   *
+   * @example
+   * const result = await store.company.update(1, { iso639: 'de', name: 'Acme', taxrate: 19, reducedtaxrate: 7 });
+   * // => { id, rootCategoryId, languageId, taxrateId, reducedtaxrateId, taxfreerateId }
+   */
   return async (id, { iso639, name, taxrate, reducedtaxrate }) => {
     const tx = pool.transaction();
     await tx.begin();