seb/dashlibstorage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite store JSDoc, split quote/order into modules, and generate typed API docs

Browse Source 
- Rewrite JSDoc across all store methods to document the actual async
  methods (real params, returns, throws) instead of the internal wrappers
- Split quote/order into individual module files backed by shared
  manifestDoc helpers; remove the createStore factory and thin wrappers
- Deduplicate manifest line helpers into src/store/manifestLines.js
- Extend generate-api-doc.js to render parameter/return/throws types and
  emit per-namespace API.<module>.md files with an API.md index
- Regenerate all API docs
This commit is contained in:
seb
2026-08-07 06:23:17 +02:00
parent 396389457f
commit aefd97a171
127 changed files with 3956 additions and 1684 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
src/store/delivery/create.js
View File

@@ -2,31 +2,33 @@ import { CREATE_MANIFEST, DELIVERY_TYPE } from '../../sql/delivery.js';
import request from '../request.js';
import resolveSelectedCompanyAccess from '../companyuser/resolveSelectedCompanyAccess.js';
import taxEnsure from '../tax/ensure.js';
import {
loadDelivery,
normalizeLines,
parseDeliveryDate,
} from './helpers.js';
import { assertSupplier, insertLines } from './writeLines.js';
import { insertLines, normalizeLines, parseDate } from '../manifestLines.js';
import { loadDelivery } from './helpers.js';
import { assertSupplier } from './writeLines.js';
/**
* Creates a new delivery for a company with its lines.
*
* @param {object} pool - The mssql connection pool.
* @returns {Function} An async function that creates a delivery.
*
* @example
* const fn = create(pool);
* const delivery = await fn(42, { number: 'D-1', date: '2026-01-01', supplierId: 5, lines: [...] });
* // => { id, number, type, entityId, date, lines: [...] }
*/
export default function create(pool) {
const access = resolveSelectedCompanyAccess(pool);
const ensureTax = taxEnsure(pool);
/**
* Creates a new delivery for the user's selected company with its lines.
*
* @param {number} googleAuthId - The id of the Google auth user.
* @param {object} body - The delivery input.
* @param {string} body.number - The delivery number.
* @param {string} body.date - The delivery date.
* @param {number} body.supplierId - The id of the supplier.
* @param {Array<object>} [body.lines] - The delivery lines.
* @returns {Promise<{id: number, number: string, type: string, entityId: number, date: string, lines: Array<object>}>} The created delivery.
* @throws {Error} If the delivery is invalid.
*
* @example
* const delivery = await store.delivery.create(42, { number: 'D-1', date: '2026-01-01', supplierId: 5, lines: [...] });
* // => { id, number, type, entityId, date, lines: [...] }
*/
return async (googleAuthId, body = {}) => {
const number = body.number?.trim?.() ? body.number.trim() : null;
const date = parseDeliveryDate(body.date);
const date = parseDate(body.date);
if (!number || !date) {
throw new Error('Invalid delivery');
}

21
src/store/delivery/delete.js
View File

@@ -1,19 +1,20 @@
import { DELETE_MANIFEST, DELIVERY_TYPE } from '../../sql/delivery.js';
import resolveSelectedCompanyAccess from '../companyuser/resolveSelectedCompanyAccess.js';
/**
* Deletes a delivery by its id within a company.
*
* @param {object} pool - The mssql connection pool.
* @returns {Function} An async function that deletes a delivery.
*
* @example
* const fn = del(pool);
* await fn(42, 5);
*/
export default function del(pool) {
const access = resolveSelectedCompanyAccess(pool);
/**
* Deletes a delivery by its id within the user's selected company.
*
* @param {number} googleAuthId - The id of the Google auth user.
* @param {number} id - The id of the delivery to delete.
* @returns {Promise<void>}
* @throws {Error} If the delivery is not found.
*
* @example
* await store.delivery.delete(42, 5);
*/
return async (googleAuthId, id) => {
if (!Number.isFinite(id)) {
throw new Error('Delivery not found');

23
src/store/delivery/getById.js
View File

@@ -1,20 +1,21 @@
import resolveSelectedCompanyAccess from '../companyuser/resolveSelectedCompanyAccess.js';
import { loadDelivery } from './helpers.js';
/**
* Returns a single delivery by its id within a company.
*
* @param {object} pool - The mssql connection pool.
* @returns {Function} An async function that fetches a delivery by id.
*
* @example
* const fn = getById(pool);
* const delivery = await fn(42, 5);
* // => { id, number, type, entityId, date, lines: [...] }
*/
export default function getById(pool) {
const access = resolveSelectedCompanyAccess(pool);
/**
* Returns a single delivery by its id within the user's selected company.
*
* @param {number} googleAuthId - The id of the Google auth user.
* @param {number} id - The id of the delivery.
* @returns {Promise<{id: number, number: string, type: string, entityId: number, date: string, lines: Array<object>}>} The delivery.
* @throws {Error} If the delivery is not found.
*
* @example
* const delivery = await store.delivery.getById(42, 5);
* // => { id, number, type, entityId, date, lines: [...] }
*/
return async (googleAuthId, id) => {
if (!Number.isFinite(id)) {
throw new Error('Delivery not found');

61
src/store/delivery/helpers.js
View File

@@ -4,6 +4,7 @@ import {
GET_DELIVERY_LINES,
} from '../../sql/delivery.js';
import request from '../request.js';
import { shapeLine } from '../manifestLines.js';
export function shapeSummary(row) {
return {
@@ -15,19 +16,6 @@ export function shapeSummary(row) {
};
}
export function shapeLine(row) {
return {
id: row.id,
articleId: row.articleId ?? null,
sku: row.sku ?? null,
amount: row.amount,
net: row.net,
rebate: row.rebate,
tax: row.tax,
comment: row.comment ?? null,
};
}
export async function loadDelivery(pool, tx, companyId, id) {
const header = await request(pool, tx)
.input('id', id)
@@ -49,50 +37,3 @@ export async function loadDelivery(pool, tx, companyId, id) {
lines: lines.recordset.map(shapeLine),
};
}
export function parseDeliveryDate(value) {
if (value instanceof Date && !Number.isNaN(value.getTime())) {
return value;
}
if (typeof value === 'string' && value.trim()) {
const d = new Date(value);
if (!Number.isNaN(d.getTime())) {
return d;
}
}
return null;
}
export function normalizeLines(lines) {
if (!Array.isArray(lines)) {
throw new Error('Invalid lines');
}
return lines.map((entry) => {
const sku = entry?.sku?.trim?.() ? entry.sku.trim() : null;
if (!sku) {
throw new Error('Invalid lines');
}
const amount = entry?.amount;
const net = entry?.net;
const rebate =
entry?.rebate === undefined || entry?.rebate === null ? 0 : entry.rebate;
const tax = entry?.tax;
const comment =
entry?.comment === undefined || entry?.comment === null
? null
: String(entry.comment);
if (
!Number.isFinite(amount) ||
!Number.isFinite(net) ||
!Number.isFinite(rebate) ||
!Number.isFinite(tax)
) {
throw new Error('Invalid lines');
}
return { sku, amount, net, rebate, tax, comment };
});
}

21
src/store/delivery/list.js
View File

@@ -2,20 +2,19 @@ import { DELIVERY_TYPE, LIST_DELIVERIES } from '../../sql/delivery.js';
import resolveSelectedCompanyAccess from '../companyuser/resolveSelectedCompanyAccess.js';
import { shapeSummary } from './helpers.js';
/**
* Lists the deliveries of a company.
*
* @param {object} pool - The mssql connection pool.
* @returns {Function} An async function that lists deliveries.
*
* @example
* const fn = list(pool);
* const deliveries = await fn(42);
* // => [{ id, number, type, entityId, date }]
*/
export default function list(pool) {
const access = resolveSelectedCompanyAccess(pool);
/**
* Lists the deliveries of the user's selected company.
*
* @param {number} googleAuthId - The id of the Google auth user.
* @returns {Promise<Array<{id: number, number: string, type: string, entityId: number, date: string}>>} The deliveries.
*
* @example
* const deliveries = await store.delivery.list(42);
* // => [{ id, number, type, entityId, date }]
*/
return async (googleAuthId) => {
const { companyId } = await access(googleAuthId);

40
src/store/delivery/update.js
View File

@@ -7,29 +7,31 @@ import {
import request from '../request.js';
import resolveSelectedCompanyAccess from '../companyuser/resolveSelectedCompanyAccess.js';
import taxEnsure from '../tax/ensure.js';
import {
loadDelivery,
normalizeLines,
parseDeliveryDate,
shapeSummary,
} from './helpers.js';
import { assertSupplier, insertLines } from './writeLines.js';
import { insertLines, normalizeLines, parseDate } from '../manifestLines.js';
import { loadDelivery, shapeSummary } from './helpers.js';
import { assertSupplier } from './writeLines.js';
/**
* Updates a delivery's header and/or lines.
*
* @param {object} pool - The mssql connection pool.
* @returns {Function} An async function that updates a delivery.
*
* @example
* const fn = update(pool);
* const delivery = await fn(42, 5, { number: 'D-2', lines: [...] });
* // => { id, number, type, entityId, date, lines: [...] }
*/
export default function update(pool) {
const access = resolveSelectedCompanyAccess(pool);
const ensureTax = taxEnsure(pool);
/**
* Updates a delivery's header and/or lines.
*
* @param {number} googleAuthId - The id of the Google auth user.
* @param {number} id - The id of the delivery to update.
* @param {object} patch - The update patch.
* @param {string} [patch.number] - The new delivery number.
* @param {string} [patch.date] - The new delivery date.
* @param {number} [patch.supplierId] - The new supplier id.
* @param {Array<object>} [patch.lines] - The new delivery lines.
* @returns {Promise<{id: number, number: string, type: string, entityId: number, date: string, lines: Array<object>}>} The updated delivery.
* @throws {Error} If the delivery is not found.
*
* @example
* const delivery = await store.delivery.update(42, 5, { number: 'D-2', lines: [...] });
* // => { id, number, type, entityId, date, lines: [...] }
*/
return async (googleAuthId, id, patch = {}) => {
if (!Number.isFinite(id)) {
throw new Error('Delivery not found');
@@ -81,7 +83,7 @@ export default function update(pool) {
let date = summary.date;
if (hasDate) {
date = parseDeliveryDate(patch.date);
date = parseDate(patch.date);
if (!date) {
throw new Error('Invalid delivery');
}

43
src/store/delivery/writeLines.js
View File

@@ -1,7 +1,3 @@
import {
CREATE_LINE,
RESOLVE_ARTICLE_ID_BY_SKU,
} from '../../sql/delivery.js';
import { GET_SUPPLIER_BY_ID, SUPPLIER_GROUP_NAME } from '../../sql/entity.js';
import request from '../request.js';
@@ -24,42 +20,3 @@ export async function assertSupplier(pool, tx, companyId, supplierId) {
}
return supplierId;
}
async function resolveArticleId(pool, tx, rootCategoryId, sku) {
const result = await request(pool, tx)
.input('rootCategoryId', rootCategoryId)
.input('sku', sku)
.query(RESOLVE_ARTICLE_ID_BY_SKU);
const articleId = result.recordset[0]?.id;
if (!articleId) {
throw new Error('Article not found');
}
return articleId;
}
export async function insertLines(
pool,
tx,
{ manifestId, rootCategoryId, lines, ensureTax },
) {
for (const line of lines) {
const articleId = await resolveArticleId(
pool,
tx,
rootCategoryId,
line.sku,
);
const taxId = await ensureTax(line.tax, tx);
await request(pool, tx)
.input('manifestId', manifestId)
.input('articleId', articleId)
.input('amount', line.amount)
.input('net', line.net)
.input('comment', line.comment)
.input('rebate', line.rebate)
.input('taxId', taxId)
.query(CREATE_LINE);
}
}