Module Placement

Module placement in universal/src

Folder structure is derived from the value-import graph. Placement is not a matter of taste — but be precise about what "derived" covers:

• Derived. Which folder owns a module, and how deep in that owner's _common chain it sits. Run the algorithm and you get exactly one answer.
• Chosen. How that owning scope is subdivided for readability. zodSchemas/, actions/, methods/ are group folders — a naming device the algorithm never emits and never forbids. Placing getBlock/ at methods/block/getBlock/ instead of directly in createClient/ is a cohesion call, not a rule.

Get the derived part wrong and it is a bug. Get the chosen part wrong and it is a review comment.

Scope: packages/near-api-ts/universal/src. types/ and tests/ do not follow this structure — never use them as evidence, and do not "fix" them unless asked. nodejs/src and browser/src are out of scope: they use a different convention and are unfinished.

Conformance is machine-checked — run pnpm check:placement. Never hand-maintain a count in this file.

Rule 0 — What counts as a consumer

Everything below depends on this definition. Get it wrong and every other rule produces garbage.

A consumer of module M is a file that imports a runtime value from M and lives in universal/src/. Nothing else is a consumer:

• import type { X } does not count. Neither does import { type X } when every specifier is type-prefixed. Only value usage creates a structural dependency.
• index.ts does not count. It re-exports from any depth; being part of the public API says nothing about where a module belongs.
• tests/ and types/ do not count. Modules cannot be cleanly grouped across src / types / tests, so only src→src edges define the hierarchy.

Counting type-only edges inflates a module's consumer set and pushes it to the wrong layer. When auditing, resolve each import and classify it before drawing conclusions.

A src module never imports from the package index.ts. A barrel import hides a value edge from this algorithm and routes around _common encapsulation. Import the module directly, however long the relative path is.

The three folder kinds

There is no further taxonomy. A group folder is not special — it does not exempt its members from anything.

Feature root is an attribute, not a kind. A direct child of src/ (createClient/, createSigner/, offchainMessage/, …) is pinned: Rules 1–2 never relocate it or its entry, whatever its consumer count says. A value import that crosses from one feature root into another is a coupling question, not a placement question — justify it or delete it.

Rule 1 — Ownership

Let C = the consumers of M, per Rule 0.

|C| == 0 → the module is free. Nothing constrains it. Put it where it is cohesive, i.e. beside the modules it belongs with conceptually. Public API entries usually land here — that is fine, index.ts reaches any depth. A free module never pins a group in place; it follows the group.

|C| == 1 → the module is private to that consumer. Put it inside the consumer's module folder. If the consumer is a bare file D/foo.ts, promote it to D/foo/foo.ts and put the module beside it. A file becomes a folder the moment it acquires its first private helper — not before.

|C| >= 2 → the module is shared. Hoist it to a _common/ of the lowest common ancestor of C, at the depth Rule 2 gives.

The threshold is exactly two. One consumer never justifies _common; two always does. The converse is a live check: a module sitting in _common with only one consumer is misplaced and must move into that consumer.

src/createClient/methods/account/
├── _common/transformAccessKey.ts        ← 2 consumers, LCA = account/
├── getAccountAccessKey/handleResult.ts  ← consumer 1
└── getAccountAccessKeys/handleResult.ts ← consumer 2

The folder's own entry counts as one of the two: createSendRequest/_common/ getAvailableRpcs.ts is used by createSendRequest.ts (the entry) and by handleMaybeUnknownBlock.ts (a private sibling).

The unit that moves

Placement moves a unit, not always a file:

• M is the entry of module folder F → the unit is F, with everything inside it. Consumers that live inside F do not count; they are internal.
• Otherwise the unit is the file itself.

Without this, "place M inside the consumer" would tear an entry away from its own private helpers and silently turn a module folder into a group folder.

Rule 2 — Layering

A chain X/_common/_common/_common/ is not nesting-by-privacy. Every layer is owned by X, visible to everything inside X — and to nothing outside X. Depth encodes how foundational a module is:

layer(M) = 1 + the deepest layer that consumes M

A regular (non-_common) module inside X is layer 0. Layer 1 serves layer 0, layer 2 serves layer 1, and so on. The invariant this produces:

A _common module never imports from an equal or shallower _common layer of the same owner. The stack is a strict dependency ladder.

Which modules have a layer

A module has a layer only if walking up from it through group folders reaches a _common directory. _common/zodSchemas/foo.ts has one (zodSchemas/ is transparent); _common/getNonConversionSteps/getRefundSteps.ts does not — it is a private member of a module folder.

A private member has no layer of its own. It inherits its enclosing _common layer, and is scored at that inherited layer when it turns up in someone else's consumer set. The invariant above is checked over the modules that have a layer.

Worked example — owner src/createClient/methods/transaction/:

transaction/
├── getTransactionResult/ , sendSignedTransaction/            layer 0
└── _common/
    ├── getExecutionFailure.ts, getExecutionSuccess.ts…       layer 1  ← used by layer 0
    └── _common/
        ├── getConversionStepSuccess.ts, getNonConversionSteps/   layer 2  ← used by layer 1
        └── _common/
            ├── getTransactionSummary.ts, getExecutionFailureError/   layer 3
            └── _common/
                └── getRawActionSummary.ts, getParsedActionSummary.ts  layer 4
                    ↑ consumed at layers 3 AND 2 → 1 + max = 4, not 1 + 2

Always take the deepest consumer.

And note how the rpc* zod schemas split, because Rule 1 runs before Rule 2. rpcActionReceipt.ts, rpcReceiptOutcome.ts and rpcTransactionSummary.ts have exactly one value consumer — rpcTransactionDetails.ts — so they are private members of _common/zodSchemas/rpcTransactionDetails/ and never get a layer at all, however many modules import type from them. rpcTransactionOutcome.ts is the one with real value consumers across the tree, which is why it alone earns a layer (2, above). Type edges are not consumers (Rule 0), so they cannot hold a module up at a layer.

Nesting does not add layers

The _common chain sets the layer once. Any folder inside that layer — module folder or group folder — inherits it. Rule 2 decides where a folder goes; it says nothing about the folder's interior, which is governed by Rule 1.

transaction/_common/_common/getNonConversionSteps/     ← layer 2, by Rule 2
├── getNonConversionSteps.ts                           ← entry
├── getReceiptsWithOutcomes.ts, getRefundSteps.ts      ← private by Rule 1, layer 2 inherited
└── getExecutionSteps/getRawExecutionStep.ts           ← same

_common is never reached into

A member of X/_common… is invisible outside X. unitConverter/ is a transparent group, so unitConverter/convertUnitsToDecimal.ts is importable from outside — but unitConverter/_common/pow10.ts is not, and never becomes so. If an outside module needs pow10, you do not reach in: re-run the algorithm and the module is hoisted out (there, to src/_common/_common/_common/pow10.ts).

The algorithm

placeModule(M):
  0. If M is a feature root or the entry of one → pinned. STOP.
     If M is the entry of module folder F → the unit is F; consumers inside F don't count.
  1. C ← files in universal/src/ that import a runtime VALUE from M
         (drop type-only imports, index.ts, tests/, types/)
  2. If |C| == 0 → free. Place with the modules it is cohesive with. STOP.
  3. If |C| == 1 → private to that consumer:
       consumer lives in module folder F → place the unit inside F
       consumer is a bare file D/foo.ts   → promote to D/foo/foo.ts, place it beside it
       STOP.
  4. X ← lowest common ancestor folder of C, with trailing `_common` segments stripped
  5. k ← max over c in C of (leading `_common` segments of c relative to X)
  6. Place the unit at  X + "/_common" repeated (k+1) times.

Step 3 names a subtree, not a directory: anywhere inside F is legal, and which group folder you land in is the "chosen" half from the top of this document.

It is a fixpoint, not a one-shot

Step 5 measures where consumers currently sit, and step 3 moves them. So a move can change k for a module whose own consumer set never changed. Re-run until nothing moves.

Triggers, all of them expected maintenance rather than churn:

• A private helper gains a second consumer in a sibling subtree → hoist to _common at the new LCA.
• A shared module loses consumers down to one → sink it into that consumer.
• A _common module starts being used by a module in its own layer → sink it one layer deeper, or Rule 2's invariant breaks.
• A consumer moved to a different _common depth → recompute step 5 for everything it imports.

Moving a module means rewriting every relative import path to it, in the same change.

Naming

• File name == the stem of its exports: getAvailableRpcs.ts exports getAvailableRpcs.
• A module may export a closed family sharing one stem — safe<Name> / throwable<Name>, <Name>ZodSchema, create<Name> / createSafe<Name>, and the z.infer types beside them. transfer.ts exporting safeTransfer + throwableTransfer + CreateTransferActionArgsSchema is one module.
• A file whose exports share no stem is two modules — split it. keyUtils.ts exporting createLock + createUnlock + createSetNonce is three files.
• Module-folder entry: <folder>.ts, always. The folder carries the entry's own name, factory or not — createCache/createCache.ts, createTasker/createTasker.ts, getBlock/getBlock.ts. Never cache/createCache.ts: a folder whose name differs from its entry reads as a group folder in the tree, and you have to open it to find out otherwise. pnpm check:placement accepts the old create<Folder>.ts form, so it will not catch a regression here — this one is on review.
• Feature roots are verb-prefixed factories (createClient/); group folders are nouns (actions/, zodSchemas/).

Types are not modules

Never create a file for a type. These stay inline in the src file:

• local arg/error shapes — type GetConversionFailureArgs = {…}, type GetXError = …
• z.infer<> results beside their schema — InnerTransaction, RpcTransactionSummary
• types coupled to a runtime value — NatError, ClientBrand

Public, user-facing types live in universal/types/, which has its own (not yet finalized) structure. Type imports never influence placement — see Rule 0.

Reference: the src/_common primitive ladder

The deepest chain in the package. It is correct — do not flatten it:

src/_common/{nearGas,nearToken,repackError,convertObjectToU8}.ts   layer 1
src/_common/_common/{asThrowable,wrapInternalError}.ts             layer 2
src/_common/_common/_common/{result,constants}.ts                  layer 3
src/_common/_common/_common/_common/natError.ts                    layer 4

natError is the most-imported module in the package and sits at the bottom precisely because everything depends on it — including result, which wrapInternalError consumes. Depth means foundational, not obscure.

Known deviations

Two, from unrelated causes. Both are recorded in scripts/checkModulePlacement/allow.json — three entries for the first, one for the second — and everything else conforms.

createSigner reaches into src/transaction/

src/transaction/ groups the action creators, signTransaction/, signDelegation/ and the schema trees all three share. It is a feature root without an entry file, so it stays a group folder, and createSigner reaches past that into its interior. Two consequences, both temporary:

• createSigner/_common/zodSchemas.ts builds TransactionIntentZodSchema out of SingleTransactionActionZodSchema and MultiTransactionActionsZodSchema, which signTransaction/zodSchemas/transaction/transaction.ts exports. That reaches into signTransaction/'s interior — the only illegal edge in the package. The module sits there because of its one legitimate consumer, signTransaction.ts (Rule 1, |C| == 1); toNearcoreTransaction/toNearcoreTransaction.ts imports from it type-only and so is not a consumer at all. Counting the createSigner edge instead would put the LCA at src/ and drag the whole zod ladder into src/_common/'s — see "Why the grouping matters" below.
• signTransaction/signTransaction.ts is consumed by two modules in createSigner/createTasker/executeTask/executors/, so the algorithm would move the whole signTransaction/ folder under executors/_common/.

Both close the same way: give transaction/ an entry factory and have createSigner consume that instead of reaching in. Until then, do not restructure around these two, and do not add new cross-feature imports like them.

getConversionSuccess.ts is placed for a method that does not exist yet

createClient/methods/transaction/_common/ holds the builders the transaction methods share — getExecutionSuccess, getExecutionFailure, getConversionFailureError, finalExecutionStatusToProcessingStage. Each is consumed from both sendSignedTransaction/ and getTransactionResult/, which puts their LCA at transaction/ and earns them that folder. getConversionSuccess.ts belongs to the same family, but today only sendSignedTransaction/handleRpcResult/getDetailsFromProcessingStage/ builds ConversionSuccess details, so with |C| == 2 inside one subtree the algorithm wants it in that folder's _common/ instead.

It stays with its siblings. This closes when client.awaitTransactionDetails is added: it is the second method that will build ConversionSuccess details, and its edge raises the LCA to transaction/, which makes the current placement the derived one. Until then, do not sink it into getDetailsFromProcessingStage/_common/ — the move would only have to be undone, and it would split one family of builders across two folders on the way.

Why the grouping matters: while the action creators sat at src/actionCreators/, the schemas they share with the sign modules had their LCA at src/, which lands them in src/_common/'s ladder — at layer 3, importing accountId and nearToken, which their own layer-0 consumers pin at layer 1. That is unsatisfiable without sinking the primitive ladder. Under one feature root the schema ladder is owned by src/transaction and is never compared against src's, since the layering check only spans same-owner edges. When a module is wanted both by feature code and by something inside src/_common/, move the consumers under a shared root rather than hoisting the module up.

Self-check

1. Did I classify every import as value vs type-only before counting consumers?
2. Did I rewrite every relative import path to the modules I moved, in the same change?
3. Did I re-run pnpm check:placement and get conforms back? The tree has no findings outside the allowlist, so any new one is mine to fix — and a move can shift a module whose own consumers never changed, so re-run until it stops reporting.