الوحدات في TypeScript: import وexport وimport type

الوحدة في TypeScript ملف فيه import أو export واحد على الأقل على المستوى الأعلى. كل ما يُعرّف فيه خاص بالملف ما لم تصدّره بـ export، والملفات الأخرى تستورد بـ import ما تحتاجه. الصياغة هي صياغة وحدات ES في JavaScript مع بعض الأشكال الخاصة بالأنواع.

// math.ts: this file is a module because it has exports.
export interface Point {
  x: number;
  y: number;
}

export const ORIGIN: Point = { x: 0, y: 0 };

export function distance(a: Point, b: Point): number {
  return Math.hypot(b.x - a.x, b.y - a.y);
}

// One default export per file, at most.
export default function describe(p: Point): string {
  return `(${p.x}, ${p.y})`;
}

const secret = 42; // not exported: invisible to other files

console.log(describe({ x: 3, y: 4 }), distance(ORIGIN, { x: 3, y: 4 })); // (3, 4) 5

التصدير المسمى والتصدير الافتراضي

في المشروع ملفات كثيرة، وجانب الاستيراد يبدو هكذا. يُستورد التصدير الافتراضي دون أقواس معقوصة ويمكن أن يأخذ أي اسم؛ أما التصديرات المسماة فتوضع بين أقواس معقوصة وتحتفظ بأسمائها ما لم تعد تسميتها بـ as.

// main.ts
import describe, { distance, ORIGIN, type Point } from "./math.js";
import { distance as dist } from "./math.js"; // renamed on import
import * as math from "./math.js";            // everything, as one object

const p: Point = { x: 6, y: 8 };
console.log(describe(p), distance(ORIGIN, p), dist(p, p), math.ORIGIN);

تتيح إعادة التصدير لملف واحد (غالبًا index.ts) أن يجمع الواجهة العامة لمجلد. أما سلوك الوحدات في JavaScript العادية، مثل الروابط الحية والتخزين المؤقت للوحدات، فمشروح في وحدات ES.

import type وexport type

الأنواع غير موجودة وقت التشغيل، لذلك لا يوجد ما يُحمّل من استيراد يُستخدم كنوع فقط. تقول import type ذلك صراحة، وتختفي العبارة من ناتج JavaScript. ويعمل المعدِّل type أيضًا على اسم واحد داخل استيراد عادي.

import type { User } from "./models.js";        // whole statement erased
import { saveUser, type Settings } from "./api.js"; // only saveUser survives

export type { User };                            // re-export a type only
export type UserId = User["id"];

دون الكلمة المفتاحية يحذف TypeScript مع ذلك الأسماء التي يرى أنها أنواع فقط. إعدادان يجعلان الكلمة إلزامية:

• verbatimModuleSyntax: true يُبقي كل استيراد غير مميز بـ type، لذلك يكون استيراد النوع غير المميز الخطأ TS1484: 'Point' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
• تشغيل ملفات .ts مباشرة في Node (حذف الأنواع، type stripping) يزيل تحديدات الأنواع لكنه لا ينظر في الملفات الأخرى. يبقى import { Point } غير المميز في الكود، وتفشل Node وقت التشغيل مع SyntaxError: The requested module './math.ts' does not provide an export named 'Point'.

كتابة type في كل استيراد للأنواع فقط تعمل في الحالتين، لذلك هي العادة التي ينبغي اكتسابها.

Cannot Find Module

عندما لا يقود المسار في الاستيراد إلى ملف أو حزمة فيها أنواع، يتوقف المترجم مع الخطأ TS2307. شغّل هذا المثال لتراه:

// This does not compile: there is no utils file next to this one.
import { formatPrice } from "./utils.js";

console.log(formatPrice(9.5));

الناتج هو index.ts(2,29): error TS2307: Cannot find module './utils.js' or its corresponding type declarations. الأسباب المعتادة:

• خطأ إملائي في مسار نسبي، أو غياب ./ (دونها يُبحث عن الاسم في node_modules).
• حزمة JavaScript لا تأتي بأنواع: ثبّت @types/{package} إذا كانت موجودة، أو اكتب لها ملف تعريفات.
• مسار فرعي لا تذكره الحزمة في الحقل exports في ملف package.json الخاص بها. مع تحليل node16 وnodenext وbundler لا يمكن استيراد إلا نقاط الدخول المذكورة.

ناتج وحدات ES أو CommonJS

أنت تكتب دائمًا import وexport. والخيار module في tsconfig.json يحدد ما يخرج من JavaScript.

// Source, the same in both cases
import { add } from "./math.js";
console.log(add(1, 2));

// module: nodenext, in a package with "type": "module"
import { add } from "./math.js";
console.log(add(1, 2));

// module: nodenext, in a package without "type": "module"
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const math_js_1 = require("./math.js");
console.log((0, math_js_1.add)(1, 2));

مع node16 أو node18 أو node20 أو nodenext يتبع TypeScript قواعد Node نفسها لكل ملف:

مع module: "esnext" أو "preserve" يحتفظ الناتج بـ import/export، وهو ما تتوقعه أدوات التجميع مثل Vite وesbuild. الفروق بين نظامي الوحدات وقت التشغيل موجودة في CommonJS مقابل ESM.

امتدادات الملفات في الاستيراد

مع module: node16 أو nodenext يجب أن يسمّي ملف وحدة ES الملف الذي ستحمّله Node فعلًا، وهو ملف .js المُترجم. ويربط TypeScript المسار ./math.js بالملف math.ts لفحص الأنواع.

import { add } from "./math";    // error TS2835 in an ES module file
import { add } from "./math.js"; // correct: the path as it exists after compiling

نص الخطأ هو Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './math.js'? أما ملفات CommonJS مع الإعدادات نفسها فيمكنها حذف الامتداد، لأن require تجرّب الامتدادات بنفسها.

إعدادان آخران يغيّران القاعدة:

• moduleResolution: "bundler" (مع ضبط module على esnext أو preserve أو commonjs) يقبل ./math دون امتداد، لأن أداة التجميع تحلّه.
• rewriteRelativeImportExtensions: true يتيح لك كتابة ./math.ts، وهو المسار نفسه الذي يعمل عندما تشغّل Node ملف .ts مباشرة، ويعيد كتابته إلى ./math.js في الناتج.

تحليل الوحدات وpaths

لاسم مجرد مثل "zod" يبحث TypeScript في node_modules، ويقرأ package.json الخاص بالحزمة (الحقلين exports وtypes)، ثم يرجع إلى node_modules/@types/zod. الأسماء النسبية (./، ../) تُحلّ انطلاقًا من الملف المستورِد. ويمكن استيراد ملف .json أيضًا؛ والإعدادات التي يحتاجها ذلك في صفحة JSON.

يضيف paths في tsconfig.json أسماء بديلة لمجلداتك:

{
    "compilerOptions": {
        "module": "esnext",
        "moduleResolution": "bundler",
        "paths": {
            "@lib/*": ["./src/lib/*"]
        }
    }
}

يؤثر paths في فحص الأنواع فقط. الملف الناتج يبقى فيه import { v } from "@lib/util"، لذلك يجب أن يحلّه شيء آخر وقت التشغيل: أداة تجميع مضبوطة على الاسم البديل نفسه، أو الحقل imports الخاص بـ Node في package.json (أسماء بديلة تبدأ بـ #، مثل "#lib/*": "./dist/lib/*")، وهو يعمل دون أي أداة إضافية. أُزيل baseUrl في TypeScript 7 (الخطأ TS5102)؛ اكتب مدخلات paths نسبةً إلى tsconfig.json مع ./ في بدايتها.