personal_genomes_project_sdk

A browser-native JavaScript SDK and demo application for retrieving, caching, and exploring publicly shared 23andMe data from the Personal Genome Project (PGP).

The toolkit supports participant discovery, profile lookup, summary statistics, and browser-based loading of genotype files for downstream analysis. It is designed to run in the browser with client-side caching through LocalForage, interactive visual summaries, and simple developer-friendly APIs for working with public PGP data.

Live Demo

https://lorenasandoval88.github.io/personal_genomes_project_sdk/

Documentation

Available in the wiki.

Quick Test (Dev Console)

You can test the SDK directly in your browser console.

const sdk = await import("https://lorenasandoval88.github.io/personal_genomes_project_sdk/dist/sdk.mjs");

const participants = await sdk.fetch23andMeParticipants(10);
const firstProfile = participants.length ? await sdk.fetchProfile(participants[0].id) : null;

console.log({ participants, firstProfile });

ES6 from npm

Use ES6 modules in two common ways:

From npm (Node/Cloud Run)

Browser SDK:

import { fetch23andMeParticipants } from "personal_genomes_project_sdk";

Node-safe SDK:

import {
  fetchAvailableDataTypes,
  allUsersMetaDataByType_fast,
  fetchProfile,
  load23andMeFile
} from "personal_genomes_project_sdk/cloud_sdk.mjs";

Architecture

personal_genomes_project_sdk/
├── src/
│   ├── js/
│   │   ├── data/get23_allUsers.js   (296 lines) - Data fetching module
│   │   ├── get23_loadStats.js       (169 lines) - Statistics loading
│   │   └── get23_main.js            (142 lines) - Main UI orchestration
│   │
│   └── css/
│       └── styles.css
│
├── server/
│   └── proxy-server.js              - Local CORS proxy
│
├── dist/                            - Build outputs
│   ├── allUsers.bundle.mjs          - All users data ESM bundle
│   ├── loadStats.bundle.mjs         - Stats ESM bundle
│   └── sdk.mjs                      - ESM module export
│
├── sdk.js                           - Public API entrypoint
├── index.html                       - Web interface
├── rollup.config.js                 - Build configuration
├── package.json                     - Dependencies & scripts
└── README.md                        - Main documentation

• src/js/: browser app modules (get23_main.js, get23_allUsers.js, get23_loadStats.js).
• src/js/data/: reusable data-fetching module (get23_allUsers.js).
• sdk.js: public SDK entrypoint (exports the API used by consumers).
• src/css/: app styles (styles.css).
• server/: local proxy server (proxy-server.js) used to bypass CORS and serve PGP-backed endpoints.
• dist/: Rollup build outputs:
  • dist/allUsers.bundle.mjs for all-users data module output.
  • dist/loadStats.bundle.mjs for stats module output.
  • dist/sdk.mjs for ESM SDK output.

 - | Directory/File       | Purpose                                                  |
| -------------------- | -------------------------------------------------------- |
| **src/**             | Source code for the application                          |
| **src/js/**          | JavaScript modules for data fetching, statistics, and UI |
| **src/css/**         | Stylesheets for the web interface                        |
| **server/**          | Local proxy server used to bypass CORS restrictions      |
| **dist/**            | Compiled build outputs generated by Rollup               |
| **sdk.js**           | Public API entry point used to expose core functionality |
| **index.html**       | Browser interface for interacting with the dataset       |
| **rollup.config.js** | Configuration file used for bundling the project         |
| **package.json**     | Project dependencies and build scripts                   |
| **README.md**        | Documentation describing the project and usage           |

Core Functions

The system is organized into three groups:

1. Public API Functions – exported functions intended for external use.
2. Internal Cache Utilities – helper functions used internally for caching.
3. UI Rendering Functions – functions responsible for displaying data in the interface.

Public API Functions

These functions are exported and can be accessed through the SDK.

| Function | File | Type | Description | |---|---|---|---| | fetch23andMeParticipants() | /src/js/data/get23_allUsers.js | async | Fetches the list of publicly available 23andMe participants from PGP. | | fetchProfile(id) | /src/js/data/get23_allUsers.js | async | Retrieves the profile JSON for a specific participant. | | getLastAllUsersSource() | /src/js/data/get23_allUsers.js | sync | Returns the source of the last participant dataset retrieval (cache or network). | | getLastProfileSource() | /src/js/data/get23_allUsers.js | sync | Returns the source of the last profile retrieval. | | load23andMeFile(path, id, cache) | /src/js/get23_loadTxts.js | async | Loads and parses a 23andMe TXT/ZIP source. Set cache=false to bypass LocalForage reads/writes. | | loadStats() | /src/js/get23_loadStats.js | async | Loads statistics about available genetic datasets (exposed through sdk.js). |

Internal Cache Utilities

These functions manage LocalForage caching and are not exported.

| Function | File | Type | Purpose | |---|---|---|---| | parseParticipants() | /src/js/data/get23_allUsers.js | sync | Parses participant HTML and extracts structured participant data. | | getCachedParticipants() | /src/js/data/get23_allUsers.js | async | Retrieves cached participant list from LocalForage. | | cacheParticipantsIfMissing() | /src/js/data/get23_allUsers.js | async | Stores participants in cache if no valid cache exists. | | getCachedProfile() | /src/js/data/get23_allUsers.js | async | Retrieves cached participant profile JSON. | | setCachedProfile() | /src/js/data/get23_allUsers.js | async | Stores participant profile data in LocalForage cache. | | getCachedStats() | /src/js/get23_loadStats.js | async | Retrieves cached dataset statistics. | | setCachedStats() | /src/js/get23_loadStats.js | async | Stores dataset statistics in cache. | | isCacheWithinMonths() | /src/js/data/get23_allUsers.js and /src/js/get23_loadStats.js | sync | Determines whether cached data is still valid based on time limits. |

UI Rendering Functions

These functions manage display logic in the browser interface.

| Function | File | Type | Description | |---|---|---|---| | displayProfiles() | /src/js/get23_main.js | async | Main controller that loads and displays participant profiles. | | renderProfilesTable() | /src/js/get23_main.js | sync | Renders the participant dataset table in the user interface. |

Architecture Summary

The architecture separates concerns into three layers:

• Data Layer – fetches participant data and profiles
• Cache Layer – stores and retrieves cached data using LocalForage
• UI Layer – renders participant information in the browser

This separation allows the system to efficiently fetch genomic data, minimize network requests through caching, and maintain a responsive browser-based interface.

load23andMeFile Usage

const sdk = await import("https://lorenasandoval88.github.io/personal_genomes_project_sdk/dist/sdk.mjs");

// Default behavior (cache enabled)
const parsedA = await sdk.load23andMeFile(pathOrUrl, "hu123ABC");

// Disable cache for this call only
const parsedB = await sdk.load23andMeFile(pathOrUrl, "hu123ABC", false);

Parameter summary:

• path: required (string URL/path or File/FileList)
• id: optional cache key suffix
• cache: optional boolean, defaults to true

Build

Run npm run build to generate:

• dist/allUsers.bundle.mjs
• dist/loadStats.bundle.mjs
• dist/sdk.mjs
• dist/cloud_sdk.mjs

SDK build targets:

• Browser SDK: dist/sdk.mjs
  • Includes browser-focused modules and caching/UI helpers.
• Node-safe SDK: dist/cloud_sdk.mjs
  • Includes ingestion-only functions for server runtimes (no window, document, or localforage).

Cloud Run style import entrypoint:

import {
  fetchAvailableDataTypes,
  allUsersMetaDataByType_fast,
  fetchProfile,
  load23andMeFile
} from "./cloud_sdk.mjs";

Package subpath import (after installing from npm):

import {
  fetchAvailableDataTypes,
  allUsersMetaDataByType_fast,
  fetchProfile,
  load23andMeFile
} from "personal_genomes_project_sdk/cloud_sdk.mjs";

Run

• Run npm run start to start the local proxy/static server on http://localhost:3000.
• Open http://localhost:3000 in your browser.
• If you use a separate static server (for example VS Code Live Server), keep the proxy running for API calls to http://localhost:3000.
• • This allows the application to access external APIs while avoiding CORS restrictions.