@sync-subscribe/server 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fromkeith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# @sync-subscribe/server
+
+Framework-agnostic sync server for `sync-subscribe`. Wire `SyncHandler` into any HTTP framework (Express, Hono, Fastify, …) to expose pull, push, and SSE streaming endpoints.
+
+## Design
+
+The server is **stateless with respect to subscriptions**. Clients send their filters and sync tokens directly in every pull/stream request — the server never stores subscription state. This means:
+
+- No subscription table in your database
+- No risk of client/server subscription desync
+- The server simply applies its own mandatory filter additions (e.g. `userId`) at request time
+
+## Concepts
+
+| Term | Description |
+|---|---|
+| `SyncRecord` | Every synced record must have `recordId`, `createdAt`, `updatedAt`, `revisionCount` |
+| `SyncStore` | Your storage adapter — implement `getRecordsSince`, `upsert`, `getById` |
+| `SyncHandler` | Orchestrates pull / push logic; decoupled from HTTP |
+| `SyncSubscriptionRequest` | One entry in a pull/stream request: `{ key, filter, syncToken }` |
+| Server filter additions | Fields the server merges into every client filter (e.g. `userId`) — invisible to the client |
+
+## Installation
+
+```bash
+npm install @sync-subscribe/server @sync-subscribe/core
+```
+
+## Quick start
+
+### 1. Define your record type
+
+```ts
+import type { SyncRecord } from "@sync-subscribe/core";
+
+interface NoteRecord extends SyncRecord {
+  userId: string;
+  title: string;
+  contents: string;
+  isDeleted: boolean;
+}
+```
+
+### 2. Implement `SyncStore`
+
+```ts
+import type { SyncStore } from "@sync-subscribe/server";
+import type { SyncPatch, SyncToken, SubscriptionFilter } from "@sync-subscribe/core";
+import { decodeSyncToken } from "@sync-subscribe/core";
+
+class NotesStore implements SyncStore<NoteRecord> {
+  async getRecordsSince(
+    subscriptions: { filter: SubscriptionFilter; since: SyncToken }[]
+  ): Promise<SyncPatch<NoteRecord>[]> {
+    // Query your DB using a union of all subscription filters,
+    // each scoped to its own since-token.
+    // Results must be ordered by (updatedAt ASC, revisionCount ASC, recordId ASC).
+    // SyncHandler deduplicates records that match multiple subscriptions.
+  }
+
+  async upsert(record: NoteRecord): Promise<NoteRecord> {
+    // INSERT OR REPLACE / ON CONFLICT DO UPDATE
+    return record;
+  }
+
+  async getById(recordId: string): Promise<NoteRecord | null> {
+    // Return record or null
+  }
+}
+```
+
+### 3. Wire up routes
+
+```ts
+import { SyncHandler } from "@sync-subscribe/server";
+import type { SyncSubscriptionRequest } from "@sync-subscribe/server";
+import type { SubscriptionFilter } from "@sync-subscribe/core";
+
+const store = new NotesStore();
+const handler = new SyncHandler<NoteRecord>(store, {
+  readonlyFields: ["createdAt"],          // clients cannot overwrite these
+  onRecordsChanged: (records) => { /* notify SSE clients */ },
+});
+
+// POST /sync/pull — pull patches for all requested subscriptions
+app.post("/sync/pull", async (req, res) => {
+  const { subscriptions } = req.body as { subscriptions: SyncSubscriptionRequest[] };
+
+  // Merge server-enforced fields into each subscription's filter.
+  // The client never sees these additions.
+  const merged = subscriptions.map((s) => ({
+    ...s,
+    filter: { ...s.filter, userId: req.user.id } as SubscriptionFilter,
+  }));
+
+  const result = await handler.pull(merged);
+  res.json(result); // { patches, syncTokens }
+});
+
+// POST /sync/push — push records from client
+app.post("/sync/push", async (req, res) => {
+  const { records } = req.body;
+  // Inject server-authoritative fields before processing
+  const sanitized = records.map((r) => ({ ...r, userId: req.user.id }));
+  const result = await handler.push({ records: sanitized });
+  res.json(result); // { ok: true, serverUpdatedAt } or { conflict: true, serverRecord }
+});
+```
+
+## SSE streaming
+
+The client opens a persistent SSE stream by POSTing its subscriptions (same shape as pull). The server sends an initial batch, then fans out future changes via `onRecordsChanged`.
+
+```ts
+import { matchesFilter, encodeSyncToken } from "@sync-subscribe/core";
+import type { SyncToken, SubscriptionFilter, StreamEvent } from "@sync-subscribe/core";
+
+interface SseConnection {
+  subscriptions: { key: string; filter: SubscriptionFilter }[];
+  res: Response;
+}
+const sseConnections = new Set<SseConnection>();
+
+const handler = new SyncHandler<NoteRecord>(store, {
+  onRecordsChanged: (records) => {
+    for (const conn of sseConnections) {
+      const patches = [];
+      const syncTokens: Record<string, SyncToken> = {};
+
+      for (const sub of conn.subscriptions) {
+        const matching = records.filter((r) =>
+          matchesFilter(r as Record<string, unknown>, sub.filter)
+        );
+        if (matching.length === 0) continue;
+
+        const last = matching[matching.length - 1]!;
+        syncTokens[sub.key] = encodeSyncToken({
+          updatedAt: last.updatedAt,
+          revisionCount: last.revisionCount,
+          recordId: last.recordId,
+        });
+        patches.push(...matching.map((r) => ({ op: "upsert" as const, record: r })));
+      }
+
+      if (patches.length > 0) {
+        conn.res.write(`data: ${JSON.stringify({ patches, syncTokens })}\n\n`);
+      }
+    }
+  },
+});
+
+// POST /sync/stream — POST-based SSE (body carries subscriptions)
+app.post("/sync/stream", async (req, res) => {
+  const { subscriptions } = req.body as { subscriptions: SyncSubscriptionRequest[] };
+
+  // Merge server filter additions
+  const merged = subscriptions.map((s) => ({
+    ...s,
+    filter: { ...s.filter, userId: req.user.id } as SubscriptionFilter,
+  }));
+
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders();
+
+  // Send initial batch
+  const initial = await handler.pull(merged);
+  res.write(`data: ${JSON.stringify(initial)}\n\n`);
+
+  // Register for future push notifications
+  const conn: SseConnection = {
+    subscriptions: merged.map((s) => ({ key: s.key, filter: s.filter })),
+    res,
+  };
+  sseConnections.add(conn);
+
+  const heartbeat = setInterval(() => res.write(": heartbeat\n\n"), 30_000);
+  req.on("close", () => {
+    clearInterval(heartbeat);
+    sseConnections.delete(conn);
+  });
+});
+```
+
+## Server-initiated writes
+
+Use `serverUpsert` for background jobs, webhooks, or inter-service writes. Unlike `push`, there is no conflict resolution — the server's intent always wins.
+
+```ts
+await handler.serverUpsert({
+  recordId: "note-abc",
+  userId: "system",
+  title: "Auto-generated",
+  contents: "...",
+  isDeleted: false,
+  createdAt: 0,       // overwritten by serverUpsert
+  updatedAt: 0,       // overwritten by serverUpsert
+  revisionCount: 0,   // incremented by serverUpsert
+});
+```
+
+`onRecordsChanged` fires after every `serverUpsert`, so SSE clients are notified automatically.
+
+## Readonly fields
+
+Fields listed in `readonlyFields` are copied from the existing server record before conflict resolution. Clients cannot overwrite them even if they try.
+
+```ts
+new SyncHandler(store, {
+  readonlyFields: ["createdAt", "userId"],
+});
+```
+
+## Conflict resolution
+
+On `push`, if the server's `revisionCount` is higher than the incoming record (or equal with an older `updatedAt`), the push returns a conflict:
+
+```ts
+// { conflict: true, serverRecord: NoteRecord }
+```
+
+The client should apply the server record locally and retry if needed. `revisionCount` acts as a "work done" counter — it doesn't depend on clocks.
+
+## API reference
+
+### `SyncHandler<T>`
+
+| Method | Description |
+|---|---|
+| `pull(subscriptions)` | Return deduplicated patches and per-key `syncTokens` for all requested subscriptions |
+| `push(req)` | Accept client records, resolve conflicts, persist, fire `onRecordsChanged` |
+| `serverUpsert(record)` | Write a record as the server; no conflict resolution; fires `onRecordsChanged` |
+
+### `SyncHandlerOptions<T>`
+
+| Option | Description |
+|---|---|
+| `readonlyFields` | Fields clients cannot modify |
+| `onRecordsChanged` | Called after every successful `push` or `serverUpsert` with the stored records |
+
+### `SyncStore<T>`
+
+| Method | Description |
+|---|---|
+| `getRecordsSince(subscriptions)` | Fetch records matching a union of `{ filter, since }` entries; ordered by `(updatedAt, revisionCount, recordId) ASC` |
+| `upsert(record)` | Write a record; return the stored record |
+| `getById(recordId)` | Return the current record for a given id, or `null` |
+| `computePartialSyncToken?(oldFilter, newFilter, token)` | Optional: compute a smarter token when a subscription filter changes |

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SyncHandler } from "./syncHandler.js";
+export type { SyncHandlerOptions, SyncStore, SyncSubscriptionRequest, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,kBAAkB,EAClB,SAAS,EACT,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SyncHandler } from "./syncHandler.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/syncHandler.d.ts

@@ -0,0 +1,41 @@
+import type { SyncRecord, SyncToken, SyncPatch, ConflictResult } from "@sync-subscribe/core";
+import type { SyncHandlerOptions, SyncStore, SyncSubscriptionRequest } from "./types.js";
+/**
+ * Core sync logic, decoupled from any HTTP framework.
+ * Wire this up to your route handlers (Express, Hono, Fastify, …).
+ *
+ * The server has no concept of stored subscriptions. The client sends its
+ * filters and sync tokens directly in every pull/stream request. The route
+ * handler is responsible for merging any server-side filter additions
+ * (e.g. userId from auth context) before calling pull().
+ */
+export declare class SyncHandler<T extends SyncRecord> {
+    private readonly store;
+    private readonly options;
+    constructor(store: SyncStore<T>, options?: SyncHandlerOptions<T>);
+    /**
+     * Pull patches for one or more subscriptions.
+     *
+     * Each entry in `subscriptions` carries an opaque `key` (echoed back in
+     * the response), a fully-merged filter (client filter + server additions),
+     * and the client's last-known sync token.
+     *
+     * Returns deduplicated patches and one sync token per key.
+     */
+    pull(subscriptions: SyncSubscriptionRequest[]): Promise<{
+        patches: SyncPatch<T>[];
+        syncTokens: Record<string, SyncToken>;
+    }>;
+    push(req: {
+        records: T[];
+    }): Promise<{
+        ok: true;
+        serverUpdatedAt: number;
+    } | ConflictResult<T>>;
+    /**
+     * Upserts a record from the server itself (background job, webhook, etc.).
+     * The server's intent always wins — no conflict resolution.
+     */
+    serverUpsert(record: T): Promise<T>;
+}
+//# sourceMappingURL=syncHandler.d.ts.map

package/dist/syncHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncHandler.d.ts","sourceRoot":"","sources":["../src/syncHandler.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,cAAc,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,kBAAkB,EAClB,SAAS,EACT,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,UAAU;IAEzC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,kBAAkB,CAAC,CAAC,CAAM;IAGtD;;;;;;;;OAQG;IACG,IAAI,CAAC,aAAa,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC;QAC5D,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;KACvC,CAAC;IAoCI,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAyCrG;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAwB1C"}

package/dist/syncHandler.js

@@ -0,0 +1,114 @@
+import { resolveConflict, matchesFilter, encodeSyncToken, } from "@sync-subscribe/core";
+/**
+ * Core sync logic, decoupled from any HTTP framework.
+ * Wire this up to your route handlers (Express, Hono, Fastify, …).
+ *
+ * The server has no concept of stored subscriptions. The client sends its
+ * filters and sync tokens directly in every pull/stream request. The route
+ * handler is responsible for merging any server-side filter additions
+ * (e.g. userId from auth context) before calling pull().
+ */
+export class SyncHandler {
+    store;
+    options;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.options = options;
+    }
+    /**
+     * Pull patches for one or more subscriptions.
+     *
+     * Each entry in `subscriptions` carries an opaque `key` (echoed back in
+     * the response), a fully-merged filter (client filter + server additions),
+     * and the client's last-known sync token.
+     *
+     * Returns deduplicated patches and one sync token per key.
+     */
+    async pull(subscriptions) {
+        const allPatches = await this.store.getRecordsSince(subscriptions.map((s) => ({ filter: s.filter, since: s.syncToken })));
+        // Compute the latest sync token per subscription key.
+        const syncTokens = {};
+        for (const sub of subscriptions) {
+            let lastMatch;
+            for (const p of allPatches) {
+                if (p.op === "upsert" &&
+                    matchesFilter(p.record, sub.filter)) {
+                    lastMatch = p.record;
+                }
+            }
+            syncTokens[sub.key] = lastMatch
+                ? encodeSyncToken({
+                    updatedAt: lastMatch.updatedAt,
+                    revisionCount: lastMatch.revisionCount,
+                    recordId: lastMatch.recordId,
+                })
+                : sub.syncToken;
+        }
+        // Deduplicate patches — last write per recordId wins across subscriptions.
+        const patchMap = new Map();
+        for (const p of allPatches) {
+            const k = p.op === "upsert" ? p.record.recordId : p.recordId;
+            patchMap.set(k, p);
+        }
+        return { patches: [...patchMap.values()], syncTokens };
+    }
+    async push(req) {
+        const { readonlyFields, onRecordsChanged } = this.options;
+        const stored = [];
+        const now = Date.now();
+        for (const incoming of req.records) {
+            const existing = await this.store.getById(incoming.recordId);
+            let record = incoming;
+            if (readonlyFields && readonlyFields.length > 0 && existing) {
+                const patched = { ...record };
+                for (const field of readonlyFields) {
+                    patched[field] = existing[field];
+                }
+                record = patched;
+            }
+            if (existing) {
+                const winner = resolveConflict(record, existing);
+                if (winner === "b") {
+                    return { conflict: true, serverRecord: existing };
+                }
+            }
+            const toStore = {
+                ...record,
+                updatedAt: now,
+                createdAt: existing ? existing.createdAt : now,
+            };
+            await this.store.upsert(toStore);
+            stored.push(toStore);
+        }
+        if (stored.length > 0) {
+            onRecordsChanged?.(stored);
+        }
+        return { ok: true, serverUpdatedAt: now };
+    }
+    /**
+     * Upserts a record from the server itself (background job, webhook, etc.).
+     * The server's intent always wins — no conflict resolution.
+     */
+    async serverUpsert(record) {
+        const { readonlyFields, onRecordsChanged } = this.options;
+        const existing = await this.store.getById(record.recordId);
+        let incoming = record;
+        if (readonlyFields && readonlyFields.length > 0 && existing) {
+            const patched = { ...incoming };
+            for (const field of readonlyFields) {
+                patched[field] = existing[field];
+            }
+            incoming = patched;
+        }
+        const now = Date.now();
+        const toStore = {
+            ...incoming,
+            updatedAt: now,
+            createdAt: existing ? existing.createdAt : now,
+        };
+        const stored = await this.store.upsert(toStore);
+        onRecordsChanged?.([stored]);
+        return stored;
+    }
+}
+//# sourceMappingURL=syncHandler.js.map

package/dist/syncHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncHandler.js","sourceRoot":"","sources":["../src/syncHandler.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import type { ConflictResult, SyncPatch, SyncRecord, SyncToken, SubscriptionFilter } from "@sync-subscribe/core";
+export type { PullRequest, PullResponse, PushRequest, PushResponse, StreamEvent, StreamRequest, } from "@sync-subscribe/core";
+export interface SyncHandlerOptions<T extends SyncRecord> {
+    /**
+     * Fields that clients cannot modify. For existing records, these values
+     * are copied from the server record before conflict resolution and storage,
+     * so client-supplied values are silently ignored.
+     */
+    readonlyFields?: readonly string[];
+    /**
+     * Called with every record successfully written to the store after a push.
+     * Use this to notify SSE subscribers, invalidate caches, etc.
+     */
+    onRecordsChanged?: (records: T[]) => void;
+}
+/**
+ * One entry in a pull or stream request.
+ * key is an opaque client-assigned identifier echoed back in the syncTokens response.
+ * filter has already had server-side additions merged in by the route handler.
+ */
+export interface SyncSubscriptionRequest {
+    key: string;
+    filter: SubscriptionFilter;
+    syncToken: SyncToken;
+}
+/**
+ * Interface that a server adapter must implement to persist and query records.
+ * Framework-agnostic; implementors plug in their own storage layer.
+ */
+export interface SyncStore<T extends SyncRecord> {
+    /**
+     * Fetch records matching one or more subscription requests, each with its own
+     * since-token. Implementations should query using a union of all filters
+     * and return patches ordered by (updatedAt, revisionCount, recordId) ascending.
+     * Deduplication across subscriptions is handled by SyncHandler.
+     */
+    getRecordsSince(subscriptions: {
+        filter: SubscriptionFilter;
+        since: SyncToken;
+    }[]): Promise<SyncPatch<T>[]>;
+    /** Write a record. Returns the stored record. */
+    upsert(record: T): Promise<T>;
+    /** Returns the current server record for a given id, or null. */
+    getById(recordId: string): Promise<T | null>;
+    /**
+     * Optional: compute a smarter sync token when a subscription filter changes,
+     * avoiding a full re-sync when only a subset of the data is new to the client.
+     */
+    computePartialSyncToken?(oldFilter: SubscriptionFilter, newFilter: SubscriptionFilter, existingToken: SyncToken): Promise<SyncToken>;
+}
+export type { ConflictResult };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,UAAU;IACtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,UAAU;IAC7C;;;;;OAKG;IACH,eAAe,CACb,aAAa,EAAE;QAAE,MAAM,EAAE,kBAAkB,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,EAAE,GAChE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAE3B,iDAAiD;IACjD,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9B,iEAAiE;IACjE,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE7C;;;OAGG;IACH,uBAAuB,CAAC,CACtB,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,kBAAkB,EAC7B,aAAa,EAAE,SAAS,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC;CACvB;AAGD,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sync-subscribe/server",
+  "version": "0.3.2",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@sync-subscribe/core": "0.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}