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

424
src/store/manifestDoc/createStore.js
View File

@@ -1,424 +0,0 @@
import {
CREATE_LINE,
CREATE_MANIFEST,
DELETE_LINES_BY_MANIFEST,
DELETE_MANIFEST,
GET_MANIFEST_HEADER,
GET_MANIFEST_LINES,
LIST_MANIFESTS,
RESOLVE_ARTICLE_ID_BY_SKU,
UPDATE_MANIFEST,
} from '../../sql/manifestDoc.js';
import {
GET_CUSTOMER_BY_ID,
POS_GROUP_NAME,
SUPPLIER_GROUP_NAME,
} from '../../sql/entity.js';
import request from '../request.js';
import resolveSelectedCompanyAccess from '../companyuser/resolveSelectedCompanyAccess.js';
import taxEnsure from '../tax/ensure.js';
function shapeSummary(type, row) {
return {
id: row.id,
number: row.number,
type,
entityId: row.entityId ?? null,
date: row.date,
};
}
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,
};
}
function parseDate(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;
}
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 };
});
}
async function assertCustomerEntity(pool, tx, companyId, entityId) {
if (entityId == null) {
return null;
}
if (!Number.isFinite(entityId)) {
throw new Error('Entity not found');
}
const result = await request(pool, tx)
.input('id', entityId)
.input('companyId', companyId)
.input('supplierGroupName', SUPPLIER_GROUP_NAME)
.input('posGroupName', POS_GROUP_NAME)
.query(GET_CUSTOMER_BY_ID);
if (!result.recordset[0]) {
throw new Error('Entity not found');
}
return entityId;
}
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;
}
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);
}
}
async function loadDoc(pool, tx, { type, companyId, id }) {
const header = await request(pool, tx)
.input('id', id)
.input('companyId', companyId)
.input('type', type)
.query(GET_MANIFEST_HEADER);
const row = header.recordset[0];
if (!row) {
return null;
}
const lines = await request(pool, tx)
.input('manifestId', id)
.query(GET_MANIFEST_LINES);
return {
...shapeSummary(type, row),
lines: lines.recordset.map(shapeLine),
};
}
/**
* Factory for quote / order (and similar) stores on manifest / manifestarticle.
*
* @param {object} pool
* @param {{ type: string, label: string }} options
* `type` → manifest.type (`quote` / `order`)
* `label` → error prefix (`Quote` / `Order` → "Quote not found")
*/
export default function createManifestDocStore(pool, { type, label }) {
const access = resolveSelectedCompanyAccess(pool);
const ensureTax = taxEnsure(pool);
const notFound = `${label} not found`;
const invalid = `Invalid ${label.toLowerCase()}`;
/**
* Lists the quote/order documents of a company.
*
* @param {number} googleAuthId - The Google auth user id.
* @returns {Promise<Array<object>>} The document summaries.
*/
async function list(googleAuthId) {
const { companyId } = await access(googleAuthId);
const result = await pool
.request()
.input('companyId', companyId)
.input('type', type)
.query(LIST_MANIFESTS);
return result.recordset.map((row) => shapeSummary(type, row));
}
/**
* Returns a single quote/order document by its id within a company.
*
* @param {number} googleAuthId - The Google auth user id.
* @param {number} id - The document id.
* @returns {Promise<object|null>} The document with its lines, or null if not found.
*/
async function getById(googleAuthId, id) {
if (!Number.isFinite(id)) {
throw new Error(notFound);
}
const { companyId } = await access(googleAuthId);
const doc = await loadDoc(pool, null, { type, companyId, id });
if (!doc) {
throw new Error(notFound);
}
return doc;
}
/**
* Creates a new quote/order document with its lines.
*
* @param {number} googleAuthId - The Google auth user id.
* @param {object} body - The document payload (`number`, `date`, `entityId`, `lines`).
* @returns {Promise<object>} The created document with its lines.
*/
async function create(googleAuthId, body = {}) {
const number = body.number?.trim?.() ? body.number.trim() : null;
const date = parseDate(body.date);
if (!number || !date) {
throw new Error(invalid);
}
const lines = normalizeLines(body.lines ?? []);
const { companyId, rootCategoryId } = await access(googleAuthId);
const tx = pool.transaction();
await tx.begin();
try {
const entityId = await assertCustomerEntity(
pool,
tx,
companyId,
body.entityId ?? null,
);
const created = await request(pool, tx)
.input('companyId', companyId)
.input('number', number)
.input('type', type)
.input('entityId', entityId)
.input('date', date)
.query(CREATE_MANIFEST);
const manifestId = created.recordset[0].id;
await insertLines(pool, tx, {
manifestId,
rootCategoryId,
lines,
ensureTax,
});
const doc = await loadDoc(pool, tx, { type, companyId, id: manifestId });
await tx.commit();
return doc;
} catch (err) {
try {
await tx.rollback();
} catch {
// ignore
}
throw err;
}
}
/**
* Updates a quote/order document's header and/or lines.
*
* @param {number} googleAuthId - The Google auth user id.
* @param {number} id - The document id.
* @param {object} patch - The fields to update (`number`, `date`, `entityId`, `lines`).
* @returns {Promise<object>} The updated document with its lines.
*/
async function update(googleAuthId, id, patch = {}) {
if (!Number.isFinite(id)) {
throw new Error(notFound);
}
const hasNumber = Object.prototype.hasOwnProperty.call(patch, 'number');
const hasDate = Object.prototype.hasOwnProperty.call(patch, 'date');
const hasEntityId = Object.prototype.hasOwnProperty.call(patch, 'entityId');
const hasLines = Object.prototype.hasOwnProperty.call(patch, 'lines');
if (!hasNumber && !hasDate && !hasEntityId && !hasLines) {
throw new Error(invalid);
}
let normalizedLines;
if (hasLines) {
normalizedLines = normalizeLines(patch.lines);
}
const { companyId, rootCategoryId } = await access(googleAuthId);
const tx = pool.transaction();
await tx.begin();
try {
const existing = await request(pool, tx)
.input('id', id)
.input('companyId', companyId)
.input('type', type)
.query(GET_MANIFEST_HEADER);
const current = existing.recordset[0];
if (!current) {
throw new Error(notFound);
}
const summary = shapeSummary(type, current);
let number = summary.number;
if (hasNumber) {
number = patch.number?.trim?.() ? patch.number.trim() : null;
if (!number) {
throw new Error(invalid);
}
}
let date = summary.date;
if (hasDate) {
date = parseDate(patch.date);
if (!date) {
throw new Error(invalid);
}
}
let entityId = summary.entityId;
if (hasEntityId) {
entityId = await assertCustomerEntity(
pool,
tx,
companyId,
patch.entityId ?? null,
);
}
await request(pool, tx)
.input('id', id)
.input('companyId', companyId)
.input('type', type)
.input('number', number)
.input('entityId', entityId)
.input('date', date)
.query(UPDATE_MANIFEST);
if (hasLines) {
await request(pool, tx)
.input('manifestId', id)
.query(DELETE_LINES_BY_MANIFEST);
await insertLines(pool, tx, {
manifestId: id,
rootCategoryId,
lines: normalizedLines,
ensureTax,
});
}
const doc = await loadDoc(pool, tx, { type, companyId, id });
await tx.commit();
return doc;
} catch (err) {
try {
await tx.rollback();
} catch {
// ignore
}
throw err;
}
}
/**
* Deletes a quote/order document by its id within a company.
*
* @param {number} googleAuthId - The Google auth user id.
* @param {number} id - The document id.
* @returns {Promise<void>}
*/
async function del(googleAuthId, id) {
if (!Number.isFinite(id)) {
throw new Error(notFound);
}
const { companyId } = await access(googleAuthId);
const result = await pool
.request()
.input('id', id)
.input('companyId', companyId)
.input('type', type)
.query(DELETE_MANIFEST);
if (!result.rowsAffected[0]) {
throw new Error(notFound);
}
}
return {
list,
getById,
create,
update,
delete: del,
};
}

64
src/store/manifestDoc/helpers.js Normal file
View File

@@ -0,0 +1,64 @@
import {
GET_MANIFEST_HEADER,
GET_MANIFEST_LINES,
} from '../../sql/manifestDoc.js';
import {
GET_CUSTOMER_BY_ID,
POS_GROUP_NAME,
SUPPLIER_GROUP_NAME,
} from '../../sql/entity.js';
import request from '../request.js';
import { shapeLine } from '../manifestLines.js';
export function shapeSummary(type, row) {
return {
id: row.id,
number: row.number,
type,
entityId: row.entityId ?? null,
date: row.date,
};
}
export async function assertCustomerEntity(pool, tx, companyId, entityId) {
if (entityId == null) {
return null;
}
if (!Number.isFinite(entityId)) {
throw new Error('Entity not found');
}
const result = await request(pool, tx)
.input('id', entityId)
.input('companyId', companyId)
.input('supplierGroupName', SUPPLIER_GROUP_NAME)
.input('posGroupName', POS_GROUP_NAME)
.query(GET_CUSTOMER_BY_ID);
if (!result.recordset[0]) {
throw new Error('Entity not found');
}
return entityId;
}
export async function loadDoc(pool, tx, { type, companyId, id }) {
const header = await request(pool, tx)
.input('id', id)
.input('companyId', companyId)
.input('type', type)
.query(GET_MANIFEST_HEADER);
const row = header.recordset[0];
if (!row) {
return null;
}
const lines = await request(pool, tx)
.input('manifestId', id)
.query(GET_MANIFEST_LINES);
return {
...shapeSummary(type, row),
lines: lines.recordset.map(shapeLine),
};
}