@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.21

package/src/helpers/code.ts

@@ -2,65 +2,69 @@ import { createIdOfLength, generateWordSlug, IdStyle, nextSlugCandidate } from '
 import { CODE_MAX, CODE_MINT_ATTEMPTS, CodeScope, CodeStyle, DEFAULT_CODE_LENGTH } from '../consts.js'
 import { CodeTaken } from '../errors.js'
 import type { CodePolicy, WorkcardDraft } from '../types.js'
+import type { CodeHelper, MintCodeOptions } from './code/types.js'
 
-export interface MintCodeOptions {
-  /** Slug style: the text the slug is derived from (a title). A word slug when omitted. */
-  seed?: string
-  /** Sequential style: how many codes the scope already holds. */
-  count?: number
-}
-
-/** `Some Title!` → `some-title`. */
-export const slugOf = (text: string, max: number = CODE_MAX): string => text
-  .normalize('NFKD').replace(/[̀-ͯ]/g, '')
-  .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
-  .slice(0, max).replace(/-+$/g, '')
+export const createCodeHelper = (): CodeHelper => {
+  const slugOf = (text: string, max: number = CODE_MAX): string => text
+    .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+    .slice(0, max).replace(/-+$/g, '')
 
-const candidateOf = (policy: CodePolicy, attempt: number, base: string, opts?: MintCodeOptions): string => {
-  const prefix = policy.prefix ?? ''
-  switch (policy.style) {
-    case CodeStyle.Slug:
-      return `${prefix}${nextSlugCandidate(base, attempt + 1)}`
-    case CodeStyle.Sequential: {
-      const number = `${(opts?.count ?? 0) + attempt + 1}`
-      return `${prefix}${policy.length != null ? number.padStart(policy.length, '0') : number}`
+  const candidateOf = (policy: CodePolicy, attempt: number, base: string, opts?: MintCodeOptions): string => {
+    const prefix = policy.prefix ?? ''
+    switch (policy.style) {
+      case CodeStyle.Slug:
+        return `${prefix}${nextSlugCandidate(base, attempt + 1)}`
+      case CodeStyle.Sequential: {
+        const number = `${(opts?.count ?? 0) + attempt + 1}`
+        return `${prefix}${policy.length != null ? number.padStart(policy.length, '0') : number}`
+      }
+      case CodeStyle.Random:
+      default: {
+        const random = createIdOfLength(policy.length ?? DEFAULT_CODE_LENGTH, IdStyle.Base58)
+        return `${prefix}${policy.uppercase === true ? random.toUpperCase() : random}`
+      }
     }
-    case CodeStyle.Random:
-    default: {
-      const random = createIdOfLength(policy.length ?? DEFAULT_CODE_LENGTH, IdStyle.Base58)
-      return `${prefix}${policy.uppercase === true ? random.toUpperCase() : random}`
+  }
+
+  const mintCode = async (
+    policy: CodePolicy,
+    taken: (code: string) => boolean | Promise<boolean>,
+    attempts: number = CODE_MINT_ATTEMPTS,
+    opts?: MintCodeOptions
+  ): Promise<string> => {
+    const seeded = opts?.seed != null ? slugOf(opts.seed, CODE_MAX - (policy.prefix?.length ?? 0) - 4) : ''
+    const base = policy.style === CodeStyle.Slug ? (seeded !== '' ? seeded : generateWordSlug()) : ''
+
+    for (let attempt = 0; attempt < attempts; ++attempt) {
+      const candidate = candidateOf(policy, attempt, base, opts)
+      if (!await taken(candidate)) {
+        return candidate
+      }
     }
+
+    throw new CodeTaken(`${policy.style}:${policy.prefix ?? ''}:${attempts}`)
   }
+
+  const codeScopeOf = (policy: CodePolicy, draft: Pick<WorkcardDraft, 'parent'>): { parent?: string } =>
+    policy.uniqueWithin === CodeScope.Parent ? { parent: draft.parent } : {}
+
+  return { slugOf, mintCode, codeScopeOf }
 }
 
-/**
- * Mint a code under a policy, asking `taken` for each candidate.
- *
- * `random` draws `prefix + Base58(length)` (upper-cased when asked) afresh per attempt; `slug`
- * walks `base`, `base-2`, `base-3` from the seed (a word slug without one); `sequential` counts on
- * from `opts.count`, zero-padded to `length`. After `attempts` taken candidates it refuses.
- *
- * @throws {CodeTaken}
- */
+export const codeHelper = createCodeHelper()
+
+/** @deprecated compat:factory-refactor — use `codeHelper.slugOf(…)` */
+export const slugOf = (text: string, max: number = CODE_MAX): string => codeHelper.slugOf(text, max)
+
+/** @deprecated compat:factory-refactor — use `codeHelper.mintCode(…)` */
 export const mintCode = async (
   policy: CodePolicy,
   taken: (code: string) => boolean | Promise<boolean>,
   attempts: number = CODE_MINT_ATTEMPTS,
   opts?: MintCodeOptions
-): Promise<string> => {
-  const seeded = opts?.seed != null ? slugOf(opts.seed, CODE_MAX - (policy.prefix?.length ?? 0) - 4) : ''
-  const base = policy.style === CodeStyle.Slug ? (seeded !== '' ? seeded : generateWordSlug()) : ''
-
-  for (let attempt = 0; attempt < attempts; ++attempt) {
-    const candidate = candidateOf(policy, attempt, base, opts)
-    if (!await taken(candidate)) {
-      return candidate
-    }
-  }
-
-  throw new CodeTaken(`${policy.style}:${policy.prefix ?? ''}:${attempts}`)
-}
+): Promise<string> => await codeHelper.mintCode(policy, taken, attempts, opts)
 
-/** Where a draft's code must be unique: its parent, or the whole entity. */
+/** @deprecated compat:factory-refactor — use `codeHelper.codeScopeOf(…)` */
 export const codeScopeOf = (policy: CodePolicy, draft: Pick<WorkcardDraft, 'parent'>): { parent?: string } =>
-  policy.uniqueWithin === CodeScope.Parent ? { parent: draft.parent } : {}
+  codeHelper.codeScopeOf(policy, draft)

package/src/helpers/index.ts

@@ -1,8 +1,21 @@
+export type * from './apply/types.js'
+export type * from './card/types.js'
+export type * from './changes/types.js'
+export type * from './code/types.js'
+export type * from './query/types.js'
+export type * from './scoped/types.js'
+export type * from './specification/types.js'
+export type * from './status/types.js'
+export type * from './validate/types.js'
+export type * from './wire/types.js'
+
 export * from './apply.js'
 export * from './card.js'
 export * from './changes.js'
 export * from './code.js'
 export * from './query.js'
+export * from './scoped.js'
 export * from './specification.js'
 export * from './status.js'
 export * from './validate.js'
+export * from './wire.js'

package/src/helpers/query/types.ts

@@ -0,0 +1,26 @@
+import type { Criteria, ListOptions, ResourceRecord } from '@owlmeans/resource'
+import type {
+  RelationshipQuery, RelationshipWhere, Specification, SpecificationQuery, SummaryView, TransitionQuery,
+  TransitionWhere, Workcard, WorkcardQuery,
+} from '../../types.js'
+import type { Scope } from '../types.local.js'
+
+/** The ONE translation of a planning query into the store's criteria, and the views read from it. */
+export interface QueryHelper {
+  /**
+   * `WorkcardQuery` → `Criteria<Workcard>` — the ONE translation every store answers, so a query
+   * means the same thing in memory, in Mongo and in a client mirror.
+   *
+   * `entityId` always comes from the scope (a query that forgot it would be a cross-tenant read);
+   * `undefined` values are omitted. Paging and sorting are {@link QueryHelper.listOptionsOf}'s.
+   */
+  criteriaOf: (query?: WorkcardQuery | null, scope?: Scope) => Criteria<Workcard>
+  /** Paging and sorting out of a query. `size: 0` (no limit) survives. */
+  listOptionsOf: <T extends ResourceRecord>(query?: ListOptions<T> | null) => ListOptions<T>
+  /** The criteria over a parent's specifications. */
+  specCriteriaOf: (parent: string, query?: SpecificationQuery | null, scope?: Scope) => Criteria<Specification>
+  linkWhereOf: (query: RelationshipQuery | null | undefined, scope: Scope) => RelationshipWhere
+  transitionWhereOf: (query: TransitionQuery | null | undefined, scope: Scope) => TransitionWhere
+  /** Counts of DIRECT children (`card.parent`) per parent, by intrinsic state. No key for a parent with none. */
+  summaryOf: (cards: Workcard[], parents: string[]) => SummaryView
+}