aidd-namespace

# Type namespace pattern Single import surface per type: `<type-name>/<type-name>.ts`. Each constant or function lives in `<exported-name>.ts`; namespace re-export from `public.js`. Types live in the `types/` layer per [structure](../aidd-structure/SKILL.md). **Precedence:** This skill defines the canonical pattern. Existing files may not yet follow it; all new work and changes must conform. Do not copy legacy structure when adding or editing code. ## File naming (utilities and constants) Inside a type folder, name each file after the single export it provides. The folder already identifies the type, so no type prefix in the filename. ```sudolang NamespaceFileNaming { typeEntry: "<type-name>.ts — type alias and namespace re-export" utilityOrConstant: "<exported-name>.ts — one file per exported function or constant; filename = export name" } Constraints { Do not use <type-name>-<exported-name>.ts for children; <exported-name>.ts is sufficient } ``` Example: under `types/point/`, files `length.ts`, `add.ts`, and `normalize.ts` each export the like-named function. ## Constant types ```sudolang ConstantVisibility { private: "Single-file only, not exported" exported: "Sole export from eponymous file" public: "Re-exported from public.ts" internal: "Exported, not in public.ts" } ``` ## Constraints ```sudolang Constraints { "<type-name>/<type-name>.ts" is the only public import surface Export a single type alias: "export type <type-name> = <type>" Export namespace: "export * as <type-name> from \"./public.js\"" In public.ts re-export every public constant file Child files: <exported-name>.ts (one export per file; filename matches export) } ``` ## Consumers ```sudolang Consumers { never: [ "Import from public.js outside the type namespace folder", "Import from any child file (e.g. schema.js, length.js) outside the type namespace folder" ] do: [ "import from <type-name>.ts only; e.g. Volume from \"../../types/volume/volume.js\"", "Access constants via the namespace: TypeName.length, etc." ] } ``` ## Extending external types When authoring helper functions for external types (e.g. String), use `StringX` as the discoverable extension namespace name. ## Type derived from schema Only for types whose source of truth is a schema. Most types do not; use a normal type alias. When the type is schema-backed, either derive it from the schema or keep a hand-written alias (e.g. for better JSDoc) and assert it matches the schema at compile time. **Option A — derive from schema:** src/types/player-mark/schema.ts ```ts export const schema = { enum: ["X", "O"] } as const; ``` src/types/player-mark/public.ts ```ts export { schema } from "./schema.js"; ``` src/types/player-mark/player-mark.ts ```ts import { Schema } from "@adobe/data/schema"; import { schema } from "./schema.js"; export type PlayerMark = Schema.ToType<typeof schema>; export * as PlayerMark from "./public.js"; ``` **Option B — hand-written object type with compile-time assertion:** Use when you want property-level JSDoc. From `@adobe/data/types`, use `Assert<Equal<YourType, Schema.ToType<typeof schema>>>` so the type stays in sync with the schema. ```ts import { Assert, Equal } from "@adobe/data/types"; import { Schema } from "@adobe/data/schema"; import { schema } from "./schema.js"; export type Bounds = { /** Left edge in world units. */ x: number; /** Top edge in world units. */ y: number; /** Width in world units. */ width: number; /** Height in world units. */ height: number; }; type _CheckSameType = Assert<Equal<Bounds, Schema.ToType<typeof schema>>>; export * as Bounds from "./public.js"; ``` ## Testing ```sudolang Constraints { Give each function file its own <same-name>.test.ts unit test } ``` ## Execute ```sudolang fn whenRefactoringToNamespace() { Constraints { Identify constants in the current file Extract them into the standard pattern Identify all consumers of public namespaces Check each consumer: imports use <type-name>.ts only, never public.js or individual child files Ensure unit tests exist per function file, splitting as needed } } ```